公共 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 链接规范 。

列表

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

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

响应实体包含三个字段：

如果您请求实体列表但没有结果，则API将使用HTTP 200 状态代码和空results数组进行响应。 在这种情情况下，它不会以 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 '{PUBLIC-KEY}:{PRIVATE-KEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/api/public/v1.0?pretty=true"

响应代码

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

Errors

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

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使用两种方法之一对请求进行身份验证： API密钥或服务帐户。这可确保用提供服务户名和密码的密钥和访问权限令牌永远不会通过网络发送。 有关使用详情，请参阅对Cloud Manager的编程访问。

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

自动化

自动化配置资源和获取最新计划的自动化状态资源提供的端点允许您修改项目的部署和检索部署状态。 您可以通过向 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 资源 。