Public API Principles

HTTP方法

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

JSON

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

链接

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

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

All entities include at least one link relation called self, which is simply its own URL. When an entity is part of a list (i.e., when requesting all hosts in a project), then it only includes the self link relation.

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
}

信封

Some clients may not be able to access the HTTP response headers and/or status code. In that case, you can request that the response include an envelope, which is simply an extra layer of information in the JSON document that contains any relevant details that would normally be in the response headers.

By default, the API does not include the response in an envelope. To request one, simply add the query parameter envelope=true.

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

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

美观打印

By default, extraneous whitespace is stripped from the JSON that Cloud Manager returns. To ask for pretty-printed JSON, simply append the pretty=true query parameter to any request:

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文档，其中包含有关错误原因的其他详细信息。 该文档包含五个字段：

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 错误代码。

身份验证

The Cloud Manager API uses one of two methods to authenticate requests: API keys or service accounts. This ensures that the keys and access tokens that serve as usernames and passwords are never sent over the network. For usage details, see Programmatic Access to Cloud Manager with a Service Account.

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

自动化

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

速率限制

某些资源受到速率限制。

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

If you exceed the rate limit, the API returns an HTTP 429 Too Many Requests response code.

更多信息

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