Princípios de API pública

Métodos deHTTP

Todos os recursos aceitam um subconjunto destes métodos comuns de HTTP:

JSON

Todas as entidades são representadas no JSON. As seguintes regras para solicitações e convenções de respostas se aplicam:

Vinculação

Cada recurso inclui um ou mais links para sub-recursos e/ou recursos relacionados.

Os links são colocados no campo links de uma entidade , que é uma array de objetos de relação de link. Cada relação de link tem dois campos:

Todas as entidades incluem pelo menos uma relação de link chamada self, que é simplesmente sua própria URL. Quando uma entidade faz parte de uma lista (ou seja, ao solicitar todos os hosts em um projeto), ela inclui apenas a relação de link 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
}

Para saber mais, consulte a Especificação de links da web.

Listas

Alguns recursos retornam uma lista de entidades.

Quando uma lista de entidades é esperada em uma resposta, os resultados são retornados em lote delimitados por dois query:

A entidade de resposta contém três campos:

Se você fizer uma solicitação de uma lista de entidades e não houver resultados, a API responderá com um código de status HTTP 200 e uma array results vazia. Ela não responde com uma 404 nesse caso, pois a lista de entidades pode não estar vazia em algum momento no futuro.

Se você tiver solicitado uma lista de entidades em um contexto que não existe (ou seja, a lista de hosts para um projeto inexistente), isso resultará em um status de resposta 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

Alguns clientes podem não conseguir acessar os cabeçalhos de resposta HTTP e/ou o código de status. Nesse caso, você pode solicitar que a resposta inclua um envelope, que é simplesmente uma camada adicional de informações no documento JSON que contém todos os detalhes relevantes que normalmente estariam nos cabeçalhos de resposta.

Por padrão, a API não inclui a resposta em um envelope. Para solicitar um, basta adicionar o parâmetro de query envelope=true.

Para respostas que contêm uma única entidade, o envelope contém dois campos:

Para respostas que contêm uma lista de entidades, já existe um envelope que envolve os resultados, portanto, especificar envelope=true como um query nesse caso apenas adiciona o campo status ao envelope existente.

Pretty printing

Por padrão, os espaços em branco estranhos são removidos do JSON que o Cloud Manager retorna. Para solicitar JSON bem impresso, basta acrescentar o parâmetro de query pretty=true a qualquer solicitação:

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

Códigos de resposta

As respostas utilizam os códigos de resposta HTTP padrão, incluindo:

Errors

Quando uma solicitação resulta em um erro, o corpo da resposta contém um documento JSON com detalhes adicionais sobre o que deu errado. O documento contém cinco campos:

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
}

Para revisar a lista de códigos, consulte Códigos de erro da API de administração do Cloud Manager.

Autenticação

A API do Cloud Manager usa um dos dois métodos para autenticar solicitações: chaves de API ou contas de serviço. Isso garante que as chaves e tokens de acesso que servem como nomes de usuário e senhas nunca sejam enviados pela rede. Para obter detalhes de uso,consulte Acesso programático ao Cloud Manager.

Alguns métodos de recursos exigem ainda mais segurança e são protegidos adicionalmente por listas de acesso que permitem o acesso ao recurso somente a partir dos endereços IP listados. Cada usuário configura sua própria lista de acesso de endereços IP que permitem acesso ao recurso.

Automação

Os recursos Recurso de Configuração de Automação e Obter Status de Automação do Plano Mais Recente fornecem endpoints que permitem modificar o sistema de um projeto e recuperar o status do sistema. Você pode modificar um sistema enviando uma nova configuração de automação para o Cloud Manager. A configuração de automação é onde você descreve e configura os processos MongoDB a serem implementados. Cloud Manager chama isso de "estado de meta" do sistema. Quando você envia uma nova configuração de automação por meio da API, as automações ajustam o estado atual do sistema para corresponder ao estado do objetivo.

Limitação de taxa

Alguns recursos estão sujeitos a limitação de taxa.

Para recursos com taxa limitada, o Cloud Manager permite até 100 solicitações por minuto por projeto. Lembre-se de que uma Public API Key é atribuída a um usuário do Cloud Manager, mas esse usuário pode acessar vários projeto.

Se você exceder o limite de taxa, a API retornará um código de resposta HTTP 429 Too Many Requests .

Informações adicionais

Consulte Recursos da API de administração do Cloud Manager para obter uma referência completa de todos os recursos disponíveis na API pública do Cloud Manager .