IBM Cloudant HTTP API 概览
0/5 (0投票)
本文档将介绍 Cloudant HTTP API 的主要组成部分。这是开发人员和架构师在开始使用 IBM Cloudant 开发解决方案之前需要了解的关键部分。
引言
本文是五篇系列文章中的第二篇，重点介绍如何开始使用 IBM Cloudant 以及如何在实际的物联网解决方案中使用它。第一篇文章演示了开始使用数据库引擎所需的基本 CRUD 操作。本文将深入探讨并讨论更多细节。我们将尝试使用不同的技术通过 Cloudant API 来管理数据。
将提供示例的源代码供下载，以帮助读者更好地理解概念和实现细节。
Cloudant REST API 简介
如果您正在构建应用程序或网站，您可能听说过 REST API，但您可能不确定这些是什么，是否应该使用它们，或者如何开始。如果听起来很熟悉，那么本文的这一部分就是为您准备的。
澄清一下：为什么是 REST API？本教程专注于 Cloudant HTTP API。
REST 和 HTTP 是同一回事吗？
不是，它们不是。HTTP 代表超文本传输协议，是一种传输文件的方式。此协议用于在我们称为万维网的环境中链接超文本页面。但是，也有其他可用的传输协议，如 FTP 和 gopher，尽管它们不太受欢迎。
表述性状态转移 (Representational State Transfer)，简称 REST，是一种架构模式。它设定了一些规则和约束，以确保系统具有可伸缩性、可靠性和易扩展性。REST 本身并非一项新发明，而是对诸如万维网之类的系统的文档。
REST 与 HTTP
大多数 RESTful API 使用 HTTP 作为传输层，但这并非强制要求。可以使用不同的协议来实现 REST API。完全可以使用 SNMP、SMTP 等其他传输协议，并且您的 API 仍然可以是 RESTful API。实际上，在我们的案例中，IBM Cloudant HTTP API 就是一个 REST API。本文将同时使用这两个术语。
背景
API：是什么以及为什么？
API 是“应用程序编程接口” (Application Programming Interface) 的缩写。在 Web 开发领域，“API”一词等同于客户端应用程序可以用来检索和更新数据的在线 Web 服务。多年来，这些在线服务曾有过几种名称/格式，例如 SOAP。然而，目前流行的选择是创建 REST（或 RESTful）API。
我们稍后将讨论为什么现在更倾向于 REST，但首先让我们看看为什么您会关心 API。
现代应用程序通常采用多层架构，其中包括各种 Web 应用程序和跨各种平台的移动应用程序。下图演示了没有 API 的这些应用程序的基本架构。在这种情况下，每个客户端应用程序都有自己的嵌入式业务逻辑。
无 API 架构
客户端应用程序拥有自己的业务逻辑（这些应用程序包含演示层和业务逻辑层）。这种方法会使客户端应用程序更加复杂，并且需要更多精力来维护这些应用程序。支持这类解决方案将非常昂贵且困难。
如果我们看同一架构，其中有一个集中式 API 来处理所有业务逻辑
HTTP API 架构简介
本节是对 HTTP API 架构的简要介绍。这些信息来自 (https://blogs.msdn.microsoft.com/martinkearn/2015/01/05/introduction-to-rest-and-net-web-api/ )
每个应用程序都使用相同的 API 来获取、更新和操作数据。
HTTP 是一个请求-响应系统，包括客户端和后端端点。客户端向端点发送请求，端点进行响应。
您应该考虑 HTTP 的几个关键要素
- 资源
- 请求动词
- 请求头
- 请求主体
- 响应正文
- 响应状态码
在 REST API 的上下文中，资源通常代表您的数据实体。请求中发送的动词告知 API 对资源执行什么操作，例如 GET 请求获取实体的数据，POST 请求创建新实体。
下表显示了您可以在电子商务 API 中看到的一些典型请求
| Resource | 动词 | 预期结果 | 响应代码 |
| /Products | GET | 系统中所有产品的列表 | 200/OK |
| /Products?Colour=red | GET | 系统中所有颜色为红色的产品列表 | 200/OK |
| /Products | POST | 创建新产品 | 201/Created |
| /Products/81 | GET | ID 为 81 的产品 | 200/OK |
| /Products/881（一个不存在的产品 ID） | GET | 某个错误消息 | 404/Not Found |
| /Products/81 | PUT | 对 ID 为 81 的产品的更新 | 204/No Content |
| /Products/81 | 删除 | 删除 ID 为 81 的产品 | 204/No Content |
| /Customers | GET | 所有客户的列表 | 200/OK |
API 参考
官方 API 参考文档可在以下网址找到： https://docs.cloudant.com/api.html
本教程介绍了如何使用 Cloudant HTTP API 的实用示例，并引用了官方文档。它涵盖了与 API 相关的几个部分。
- HTTP 头和 HTTP 状态码
- 身份验证
- 数据库
- Documents
- 查询
其他部分将在本培训的后续部分中隐式引用。
Cloudant HTTP API
有关 HTTP API 的所有详细信息，您可以在 Cloudant 文档中找到：( https://docs.cloudant.com/http.html ) 在这里，我们将只提及此 API 最重要的部分。
HTTP 头
支持的 HTTP 请求头包括
- 接受
- Content-Type
- If-None-Match
接受
Accept 头用于指定允许作为服务器响应类型的数据类型。它指定格式可以是由冒号分隔的一个或多个 MIME 类型列表。在 Cloudant 查询中使用 Accept 头不是必需的，但强烈推荐。它有助于确保返回的数据可以被客户端处理。
Content-Type
Content-Type 头指定请求内返回信息的类型。
Content-Encoding
此头指定请求体的编码。
HTTP 状态码
通过与 Cloudant 的接口，错误代码和状态会通过 HTTP 状态码数字和响应数据主体中的相应数据组合进行报告。
- 401 - Unauthorized (未授权)
- 403 - Not Found (未找到)
- 405 - Resource Not Allowed (资源不允许)
- 406 - Not Acceptable (不可接受)
- 409 - Conflict (冲突)
- 412 - Precondition Failed (前提条件失败)
- 415 - Bad Content Type (内容类型错误)
身份验证
客户端可以通过两种方式向 Cloudant 提供凭据（进行身份验证）：基本身份验证和 Cookie 身份验证。基本身份验证是每个请求的身份验证。Cookie 身份验证类似于拥有一个密钥（基于 Cookie），由客户端决定何时离开。密钥是一个名为 AuthSession 的 Cookie。有关身份验证的更多详细信息，请参阅 Cloudant 文档：(https://docs.cloudant.com/authentication.html)
数据库
数据库有几种主要的 CRUD 操作
- 创建新数据库
- 读取指定数据库的信息
- 删除指定数据库
- 获取特定帐户下的所有数据库
- 获取数据库中的所有文档
当您向特定数据库发出 REST 请求时，所需的 URL 是
https://$USERNAME.cloudant.com/$DATABASE
创建新数据库
创建新数据库需要 `PUT` 请求，删除数据库需要 `POST` 请求。所有其他请求都是 `GET` 请求。
列出帐户中的所有数据库
此功能可以通过向 https://$USERNAME.cloudant.com/_all_dbs 发送 `GET` 请求来实现。
列出数据库中的所有文档
本节信息来自 Cloudant 文档：(https://docs.cloudant.com/database.html)
要列出数据库中的所有文档，请向
https://$USERNAME.cloudant.com/$DATABASE/_all_docs
发送 `GET` 请求。_all_docs 端点接受以下查询参数
获取数据库中的所有文档
GET /_all_dbs HTTP/1.1
获取数据库中至少匹配一个指定键的文档
GET /_all_docs?keys=["somekey","someotherkey"] HTTP/1.1
Documents
您可以通过 Cloudant API 对文档执行 CRUD 操作。文档是 JSON 对象。文档是数据的容器，也是 Cloudant 数据库的基础。所有文档必须包含两个字段：唯一的 _id 字段和 _rev 字段。以“_”字符开头的字段名称在 Cloudant 中是保留的。
以下是如何处理文档的几个示例。
创建
要创建文档，请将包含文档 JSON 内容的 POST 请求发送至
https://$USERNAME.cloudant.com/$DATABASE.
创建文档
POST /$DATABASE HTTP/1.1
Content-Type: application/json
{
"_id": "phone",
"brand": "Nokia",
"prices": {
"530": 49.99,
"630": 74.99,
"950": 450.99
}
}
示例响应
{
"ok":true,
"id":"phone",
"rev":"1-2902191555"
}
读取
要检索文档，请向 https://$USERNAME.cloudant.com/$DATABASE/$DOCUMENT_ID 发送 GET 请求。如果您不知道特定文档的 _id，可以查询数据库以获取所有文档。
查询参数
这是您可以按常规方式添加到 URL 的参数列表，例如 /db/doc?attachments=true&conflicts=true。所有参数都是可选的。
读取文档
GET /$DATABASE/$DOCUMENT_ID HTTP/1.1
示例响应
{
"_id": "phone",
"_rev": "1-2902191555",
"brand": "Nokia",
"prices": {
"530": 49.99,
"630": 74.99,
"950": 450.99
}
}
有关 Cloudant 文档 API 的更多详细信息，请访问：(https://docs.cloudant.com/document.html)
查询
Cloudant 查询是为 Cloudant 数据库提供声明式 JSON 查询语法的功能。在 IBM Cloudant 中，有两种不同的查询类型：MapReduce 视图（索引类型为 JSON）和搜索索引（索引类型为文本）。本节仅提及与这些查询相关最重要的内容。您可以在本教程的后续两篇文章中找到更多详细信息。
您可以使用以下操作进行查询
- 创建索引
- 删除索引
- 列出索引
- 查找文档
选择器
选择器是与查询相关的元素。选择器语法要求您指定一个或多个字段以及这些字段所需的相应值。
创建名为 `region` 的字段的新索引的示例
{
"index": {
"fields": ["region"]
},
"name" : "region-index",
"type" : "json"
}
有关 Cloudant 查询的更多详细信息，请访问：(https://docs.cloudant.com/cloudant_query.html)
REST API 请求工具
cURL
cURL 是一个辅助应用程序，允许通过命令行使用不同协议进行数据传输操作。cURL 可用于几乎所有现有的平台。
您可以从此链接下载 cURL 的最新版本：https://curl.haxx.se/
Fiddler
Fiddler 是一个捕获 HTTP 和 HTTPS 流量并将其记录供用户审查的工具。此应用程序还可用于在 HTTP 流量发送或接收时对其进行修改（“处理”），以便进行故障排除。默认情况下，HTTP(S) 堆栈的流量在运行时会自动定向到代理，但任何 Web 应用程序都可以配置为通过 Fiddler 路由其流量。Fiddler 由 Eric Lawrence 编写。第一个版本发布于 2003 年。
自 2012 年以来，Fiddler 已成为 Telerik（现为 Progress Software）的产品。
您可以在此处下载 Fiddler：https://www.telerik.com/download/fiddler
如果您更喜欢使用浏览器扩展，Chrome 和 Firefox 有多种扩展。下面提到了一些比较流行的扩展。
Chrome REST 扩展
- Postman：http://www.getpostman.com/
- Insomnia REST Client：http://insomnia.rest/
- Advanced REST client：https://chromerestclient.appspot.com/
Firefox 插件
- REST Easy：https://addons.mozilla.org/en-US/firefox/addon/rest-easy/
- RESTClient：https://addons.mozilla.org/en-US/firefox/addon/restclient/
- RESTer：https://addons.mozilla.org/en-US/firefox/addon/rester/
Postman 的示例屏幕
Using the Code
有许多适用于不同平台的 REST 服务库。我们将重点介绍 .Net 和 JavaScript/jQuery 上的实现。
Cloudant 的 .NET REST 客户端实现
实现 IBM Cloudant REST 客户端的最简单方法是使用一些 .NET 的 REST 客户端库。
可能是最流行的框架是 RestSharp http://restsharp.org/。您可以从 GitHub 下载源代码，或者直接使用 NuGet 包管理器引用库。
下面是一个示例代码，它获取特定数据库的信息。演示了两种不同的请求执行方式：同步和异步。
class Program
{
static void Main(string[] args)
{
var client = new RestClient();
client.BaseUrl = new Uri("https://mikeamm.cloudant.com/pouchrecords");
client.Authenticator = new HttpBasicAuthenticator("username", "password");
var request = new RestRequest(Method.GET);
// easily add HTTP Headers
request.AddHeader("Content-Type", "application/json");
//unfinite loop until esc key is pressed
Console.WriteLine("Press ESC to stop");
do
{
IRestResponse syncresponse = client.Execute(request);
Console.WriteLine(syncresponse);
// easy async support
client.ExecuteAsync(request, response => {
Console.WriteLine(response.Content);
});
} while (Console.ReadKey(true).Key != ConsoleKey.Escape);
}
}
示例响应显示在下面的屏幕截图中。
如果您不想深入研究细节，可以直接使用上一篇文章中用于 IBM Cloudant 的 *System.Net.Http.dll*。
JavaScript 和 jQuery 与 Cloudant REST API
您可以使用 `XMLHttpRequest` 对象（JavaScript）或 jQuery 的 `jQuery.ajax()` 方法来管理 REST API。下面的示例演示了如何使用 `XMLHttpRequest` 对象。
function createRequest() {
var result = null;
if (window.XMLHttpRequest) {
// FireFox, Safari, etc.
result = new XMLHttpRequest();
if (typeof xmlhttp.overrideMimeType != 'undefined') {
result.overrideMimeType('text/xml'); // Or anything else
}
}
else if (window.ActiveXObject) {
// MSIE
result = new ActiveXObject("Microsoft.XMLHTTP");
}
else {
// No known mechanism -- consider aborting the application
}
return result;
`XMLHttpRequest` 对象允许您发送 GET 或 POST 请求；但是，它不会立即返回值。
var req = createRequest(); // defined above
// Create the callback:
req.onreadystatechange = function() {
if (req.readyState != 4) return; // Not there yet
if (req.status != 200) {
// Handle request failure here...
return;
}
// Request successful, read the response
var resp = req.responseText;
// ... and use it as needed by your app.
}
发送请求
创建请求对象并设置回调函数后，就可以发出请求了。
req.open("GET", url, true);
req.send();
如何使用 jQuery 消费 RESTful 服务
这是如何使用最流行的 JavaScript 框架 jQuery 消费 RESTful 服务的实际案例。在 jQuery 中，有一个 `jQuery.ajax()` 函数，可用于与 REST 服务进行通信。
下面的示例代码摘自以下帖子：(http://www.lm-tech.it/Blog/post/2013/05/08/How-to-consume-a-RESTful-service-using-jQuery.aspx)
jQuery.ajax({
type: "GET|POST|DELETE|PUT",
url: url,
data: data,
dataType:"text|html|json|jsonp|script|xml"
success: success_callback,
error: error_callback
});
如何在现代 Web 应用程序中使用此方法？实际上，使用 REST 接口实现所有查询是一项相对艰巨的任务，尽管可以使用一些库或 PouchDB。
PouchDB
PouchDB 是一个轻量级的开源 JavaScript 数据库，旨在在浏览器中良好运行。PouchDB 的实现灵感来自 Apache CouchDB。此解决方案旨在帮助 Web 开发人员构建能够在线和离线工作的应用程序。PouchDB 使 Web 应用程序可以在离线时将数据本地存储。当应用程序重新联机时，将与 CouchDB 和兼容服务器进行同步。有关更多详细信息，请访问 PouchDB 网站（https://pouchdb.com/ ）
IBM Cloudant 基于 CouchDB。好消息是 PouchDB 也兼容 Cloudant。
如果您需要同步数据库，则需要考虑一些细节：您需要从 Cloudant 获取数据，并与 PouchDB 客户端同步。
PouchrecordsObj = function (databasename, remoteorigin)
{
// define proeprties
this.opts =
{
continuous: true
};
this.pdb = new PouchDB(databasename);
this.remote = remoteorigin + '/'+databasename, this.opts;
his.pdb.replicate.from(this.remote, this.opts);
};
双向复制通过以下函数实现
this.pdb.replicate.to(this.remote, this.opts);
this.pdb.replicate.from(this.remote, this.opts);
下面演示的客户端允许在线和离线使用 Cloudant。如果 Internet 连接不可用，数据将存储在浏览器的本地存储中，当连接恢复时，本地数据将与 Cloudant 数据库同步。
您可以在下面看到示例 PouchDB 客户端的一些屏幕截图。
源代码
示例可在 GitHub 上找到
- Cloudant .NET REST 客户端（使用 RestSharp）
- Cloudant 物联网模拟设备
- Sample PouchDemo 客户端，同步有关物联网报告的数据到 Cloudant 数据库
物联网客户端模拟设备是上一篇文章“Getting Started with Cloudant” 中设备的扩展版本。
物联网客户端和 Web Pouch 客户端都是将在后续文章中讨论的物联网解决方案的一部分。
摘要
本教程介绍了如何开始使用 Cloudant HTTP API。它涵盖了 REST 服务的基础知识，以及使用以下方法发送 REST 请求的各种方式：
- Fiddler 等开发工具、REST 浏览器扩展
- .NET 的 RestSharp
- Web 应用程序的 JavaScript 和 jQuery
还提供了有关如何在 Web 客户端中使用 PouchDB 进行 CRUD 操作的示例，这将大大简化 Cloudant Web 客户端的实现。