Referência da API de administração do Atlas

Métodos deHTTP

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

JSON

Todas as entidades são representadas noJSON. Aplicam-se as seguintes regras e convenções:

• Cabeçalho de solicitação de tipo de conteúdo

  Ao enviar JSON para o servidor via POST ou PUT, certifique-se de especificar o cabeçalho de solicitação do tipo de conteúdo correto: Content-Type: application/json

• Campos inválidos

  Campo inválidos são rejeitados em vez de ignorados. Por exemplo, se você tentar criar uma nova entidade e digitar incorretamente um dos campos, ou tentar atualizar uma entidade existente e incluir um campo que não possa ser modificado, o servidor responderá com um código de status 400 e uma mensagem de erro informando qual o campo é inválido.

• Datas formatadas em ISO-8601

  Todas as datas são retornadas como strings formatadas emISO- designadas em UTC.8601 Ao enviar datas para o servidor (ou seja, como parâmetros de consulta ou campos em POST ou PATCH entidades de solicitação), use datas no formato ISO8601. Se você não especificar um fuso zona, o UTC será presumido. No entanto, é altamente recomendável que você inclua um designador de fuso zona para evitar qualquer ambiguidade.

• Carimbos de data/hora BSON

  Em alguns casos, um carimbo de data/hora é retornado como carimbo de data/hora BSON, principalmente nos recursos de backup. Eles são representados em documentos JSON como um objeto com dois campos: date, que é uma string de caracteres de data formatada em ISO8601em UTC com granularidade para o segundo, e increment um inteiro de 32bits.

• Nomes de campo para campos com números

  Os campos que contêm valores numéricos em uma unidade específica serão nomeados para diferenciar a unidade que está sendo usada.

• Campos vazios

  Os campos que não possuem um valor atual são retornados com um valor padrão apropriado.

  Os campos que não possuem um valor padrão razoável são omitidos da entidade.

• Ordem do campo

  Os campos nos documentos JSON retornados pelo servidor não estão em uma ordem específica, e a ordem pode mudar. Não dependa da ordem dos campos.

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, ela inclui somente a relação de link self .

Para obter mais informações, consulte a Especificação de vinculação da web. Observe que, embora a especificação descreva um formato para incluir links nos cabeçalhos de resposta HTTP, isso não é obrigatório. Para tornar a API de administração do Atlas facilmente navegável, ela inclui os links no corpo da resposta em vez de nos cabeçalhos de resposta.

Listas

Alguns recursos retornam uma lista de entidades. Quando uma lista de entidades é esperada em uma resposta, os resultados são retornados em lotes limitados pelos seguintes parâmetros de consulta:

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 de administração do Atlas responderá com um código de status 200 e a array results estará vazia. Ela não responde com uma 404 nesse caso, pois a lista de entidades pode não estar vazia em algum ponto no futuro. No entanto, se você solicitar uma lista de entidades em um contexto que não existe (por exemplo, a lista de hosts para um projeto inexistente), isso resultará em um status de resposta 404.

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 e contém todos os detalhes relevantes que normalmente estariam nos cabeçalhos de resposta. Por padrão, a API de Administração do Atlas 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 apenas adiciona o campo status ao envelope existente.

Pretty printing

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

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

Códigos de resposta

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

Errors

Quando uma solicitação retorna um erro, o corpo da resposta contém um documento JSON. Este documento inclui detalhes sobre o motivo da falha na solicitação da API de administração do Atlas. O documento contém cinco parâmetros:

1
{
2
  "detail" : "Cannot find resource /api/atlas/v1.0/softwareComponents/version.",
3
  "error" : 404,
4
  "errorCode" : "RESOURCE_NOT_FOUND",
5
  "parameters" : [ "/api/atlas/v1.0/softwareComponents/version" ],
6
  "reason" : "Not Found"
7
}

ID do Projeto

Seu ID do projeto é um valor de string que identifica exclusivamente um projeto do Atlas.

Os projetos do Atlas foram identificados anteriormente como "grupos". Alguns endpoints do Atlas fazem referência a group ou {GROUP-ID} como parte do caminho da solicitação, da query ou dos parâmetros do corpo. Para qualquer endpoint que exija {GROUP-ID}, especifique o ID do projeto.

Para recuperar seu ID do projeto:

Autenticação

A API de administração do Atlas usa um dos dois métodos para autenticar solicitações: chaves deAPI ou contas de serviço. Isso garante que as chaves e os tokens de acesso que servem como nomes de usuário e senhas nunca sejam enviados pela rede. Para saber mais,consulte autenticação da API de administração do Atlas .

Para detalhes de uso, consulte Criar uma solicitação de API.

Limitação de taxa

Alguns recursos limitam quantas solicitações podem processar por minuto.

Para esses recursos, o Atlas permite até 100 solicitações por minuto por projeto. Os métodos de autenticação da API de Administração do Atlas pertencem a uma organização, mas podem ter acesso a vários projetos.

Se você exceder o limite de taxa, a API de administração do Atlas retornará um 429 (Solicitações demais) Código de statusHTTP .

Próximos passos

Para começar, consulte Introdução à API do Atlas Administration.

Para gerenciar o acesso de programação à API de administração do Atlas, consulte qualquer um dos seguintes procedimentos:

• Gerenciar acesso de programação a uma organização.

• Gerenciar acesso de programação a múltiplas organizações.

• Gerenciar acesso de programação a um projeto.