公共 API原则

HTTP方法

所有资源都支持这些常用 HTTP 方法的子集：

JSON

所有实体均以JSON表示。 以下请求规则和响应约定适用：

链接

每个资源包括一个或多个指向子资源的链接和/或相关资源。

链接放置在实体的links字段中，该实体是链接关系对象的数组。 每个链接关系都有两个字段：

所有实体都至少包含一个名为self的链接关系，即实体自己的URL 。 当实体是列表的一部分时（即，请求项目中的所有主机时），它仅包含self链接关系。

1
{
2
  "id": "xxx",
3
  "projectId": "yyy",
4
  "hostname": "mongodb.example.com",
5
  "port": 27017,
6
  "links": [
7
    {
8
      "rel": "self",
9
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx/hosts/yyy"
10
    },
11
    {
12
      "rel": "http://mms.mongodb.com/project",
13
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
14
    }
15
  ]
16
}

要了解更多信息，请参阅 Web 链接规范 。

列表

某些资源会返回实体列表。

当响应中需要实体列表时，结果将在两个查询参数的限制下批处理返回：

响应实体包含三个字段：

If you make a request for a list of entities and there are no results, then the API responds with an HTTP 200 status code and an empty results array. 在这种情情况下，它不会以 404 进行响应，因为实体列表在将来的某个点可能不为空。

如果您在不存在的上下文中请求实体列表（即不存在的项目的主机列表），则会导致HTTP 404 响应状态。

1
{
2
3
  "totalCount": 57,
4
  "results": [
5
    {
6
      "id": "yyy",
7
      "projectId": "xxx",
8
      // additional host properties...
9
    },
10
    // additional host documents...
11
  ],
12
  "links": [
13
    {
14
      "rel" : "self",
15
      "href" : "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?pageNum=2&itemsPerPage=10"
16
    },
17
    {
18
      "rel": "previous",
19
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=1"
20
    },
21
    {
22
      "rel": "next",
23
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=3"
24
    }
25
  ]
26
}

信封

某些客户端可能无法访问HTTP响应标头和/或状态代码。 在这种情况下，您可以请求响应包含envelope ，它只是JSON文档中的额外信息层，其中包含通常位于响应标头中的任何相关详细信息。

默认情况下， API不会将响应包含在信封中。 要请求一个，只需添加查询参数envelope=true即可。

对于包含单个实体的响应，信封包含两个字段：

对于包含实体列表的响应，已经有一个封装结果的信封，因此在这种情况下指定envelope=true作为查询参数只会将status字段添加到现有信封。

美观打印

默认情况下，会从 Cloud Manager 返回的JSON中去掉多余空格。 要请求美观打印的JSON ，只需将pretty=true查询参数附加到任何请求：

curl --user '{USERNAME}:{APIKEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/api/public/v1.0?pretty=true"

响应代码

响应利用标准HTTP响应代码，包括：

错误

当请求导致错误时，响应正文会包含一个JSON文档，其中包含有关错误原因的其他详细信息。 该文档包含五个字段：

1
{
2
  "detail" : "Cannot find resource /api/public/v1.0/softwareComponents/version.",
3
  "error" : 404,
4
  "errorCode" : "RESOURCE_NOT_FOUND",
5
  "parameters" : [ "/api/public/v1.0/softwareComponents/version" ],
6
  "reason" : "Not Found"
7
}

要查看代码列表，请参阅Cloud Manager Administration API 错误代码。

身份验证

如前所述，Cloud Manager API使用HTTP摘要式身份验证。摘要式身份验证的详细信息超出了本文档的范围，但它本质上需要用户名和密码，使用服务器生成的唯一值（称为随机数）对这两个用户名和密码进行哈希处理。用户名是已注册 Cloud Manager 帐户的用户名，密码是与该帐户关联的公共 API 密钥。

请记住以下几点：

• 客户端使用服务器生成的随机数对用户名和密码进行哈希处理，然后将其发送回服务器以对请求进行身份验证。 根据摘要式身份验证规范，该随机数仅在短时间内有效。 这是为了防止重放攻击，因此您无法缓存随机数并永久使用它。

• 将摘要式身份验证与HTTPS结合使用，可确保密码永远不会传回服务器，从而提供额外的安全层。

• 某些资源方法需要更高的安全性，并且还受到访问列表的额外保护，该列表只允许从列出的IP地址访问资源。 每个用户都配置自己的IP地址访问列表，允许访问资源。

• Cloud Manager 有一个角色的概念，它允许对允许用户执行的操作进行更细粒度的控制。API资源也执行相同的授权规则，因此可以通过API密钥访问的资源和方法由授予关联用户的角色控制。

  例子

  对于DELETE主机，拥有用于发出请求的API密钥的用户必须是主机所属项目中的Project Monitoring Admin或Project Owner 。

• 许多资源都与项目（以前称为群组）绑定，以下形式的URL即可证明：

  /api/public/v1.0/groups/{PROJECT-ID}/

  对于这些资源，与API密钥绑定的用户必须是项目成员。 否则，Cloud Manager 将使用HTTP 401 错误进行响应。

自动化

自动化配置资源和获取最新计划的自动化状态资源提供的端点允许您修改项目的部署和检索部署状态。 您可以通过向 Cloud Manager 发送新的自动化配置来修改部署。 您可以在自动化配置中描述和配置要部署的 MongoDB 进程。 Cloud Manager 将此称为部署的“目标状态”。当您通过API提交新的自动化配置时，自动化会调整系统的当前状态以匹配目标状态。

速率限制

某些资源受到速率限制。

对于受到速率限制的资源，Cloud Manager 允许每个项目每分钟最多 100 个请求。 请记住，公共API密钥会分配给 Cloud Manager 用户，但该用户可以访问多个项目。

如果超过速率限制， API将返回HTTP 429 Too Many Requests响应代码。

更多信息

有关 Cloud Manager 公共 API 中提供的所有资源的完整参考，请参阅 Cloud Manager Administration API 资源 。