공개 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 는 HTTP 다이제스트 인증을 사용합니다. 다이제스트 인증에 대한 자세한 내용은 이 문서의 범위를 벗어나지만, 기본적으로 논스( nonce) 라는 서버 생성 고유 값을 사용하여 해시되는 사용자 이름과 비밀번호가 필요합니다. 사용자 이름은 등록된 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 관리 API 리소스 를 참조하세요.