공개 API 원칙

HTTP 메서드

모든 리소스는 다음과 같은 일반적인 HTTP 메서드의 하위 집합을 지원합니다.

JSON

모든 엔터티는 JSON 으로 표시됩니다. 요청에는 다음 규칙과 응답 규칙이 적용됩니다.

연결

각 리소스에는 하위 리소스 및/또는 관련 리소스에 대한 링크가 하나 이상 포함되어 있습니다.

링크는 링크 관계 객체의 배열인 엔터티의 links 필드에 배치됩니다. 각 링크 관계에는 두 개의 필드가 있습니다.

모든 엔터티에는 자체 URL 인 self 이라는 링크 관계가 하나 이상 포함되어 있습니다. 엔터티가 목록의 일부인 경우(즉, 프로젝트의 모든 호스트를 요청하는 경우) 여기에는 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
}

자세한 내용은 웹 연결 사양 을 참조하세요. .

목록

일부 리소스는 엔터티 목록을 반환합니다.

응답에서 엔터티 목록이 예상되는 경우 결과는 두 개의 쿼리 매개변수에 의해 제한된 배치로 반환됩니다.

응답 엔터티에는 세 개의 필드가 포함되어 있습니다.

엔터티 목록을 요청했는데 결과가 없는 경우 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
}

Envelopes

일부 클라이언트는 HTTP 응답 헤더 및/또는 상태 코드에 액세스하지 못할 수 있습니다. 이 경우 응답에 envelope 을 포함하도록 요청할 수 있으며, 이는 일반적으로 응답 헤더에 있는 관련 세부 정보를 포함하는 JSON 문서의 추가 정보 계층일 뿐입니다.

기본적으로 API 는 엔벨로프에 응답을 포함하지 않습니다 . 요청하려면 쿼리 매개변수 envelope=true 를 추가하기만 하면 됩니다.

단일 엔터티가 포함된 응답의 경우 엔벨로프에는 다음과 같은 두 개의 필드가 포함됩니다.

엔터티 목록이 포함된 응답의 경우 결과를 래핑하는 엔벨로프가 이미 있으므로 이 경우 envelope=true 을 쿼리 매개 변수로 지정하면 기존 엔벨로프에 status 필드만 추가됩니다.

Pretty Printing

기본적으로 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 응답 코드를 활용합니다.

오류

요청 결과에 오류가 발생하면 응답 본문에 무엇이 잘못되었는지에 대한 추가 세부 정보가 포함된 JSON 문서가 포함됩니다. 문서에는 다음과 같은 5개의 필드가 있습니다.

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 관리 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 관리 API 리소스 를 참조하세요.