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
  "rel": "http://mms.mongodb.com/project",
3
  "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
4
  "id": "xxx",
5
  "projectId": "yyy",
6
  "hostname": "mongodb.example.com",
7
  "port": 27017,
8
  "links": [
9
    {
10
      "rel": "self",
11
      "href": "https://<ops-manager-host>/api/public/v1.0/projects/xxx/hosts/yyy"
12
    },
13
    {
14
      "rel": "http://mms.mongodb.com/project",
15
      "href": "https://<ops-manager-host>/api/public/v1.0/projects/xxx"
16
    }
17
  ]
18
}

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 Ops Manager retorna. 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 "{opsManagerHost}:{Port}/api/public/v1.0?pretty=true"

Códigos de resposta

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

Erros

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 Ops Manager.

Autenticação

Como mencionado anteriormente, a do MongoDB Ops Manager API usa HTTP a Autenticação Digest. Os detalhes da autenticação digest estão além do escopo deste documento, mas ela requer essencialmente um nome de usuário e uma senha que são criptografados usando um valor exclusivo gerado pelo servidor chamado nonce. O nome de usuário é o nome de usuário de uma conta registrada do MongoDB Ops Manager , e a senha é uma chave de API pública associada a essa conta.

Tenha em mente os seguintes pontos:

• O nonce gerado pelo servidor é usado pelo cliente para fazer o hash do nome de usuário e da senha antes de enviá-los de volta ao servidor para autenticar uma solicitação. O nonce só é válido por um curto período de tempo, de acordo com a especificação da autenticação digest. This is to prevent replay attacks, so you cannot cache a nonce and use it forever.

• 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.

• O aplicativo Ops Manager tem um conceito de roles, que permitem um controle mais preciso das operações que um usuário pode executar. Os recursos da API também impõem as mesmas regras de autorização, portanto, os recursos e métodos que podem ser acessados por uma chave de API são regidos pelas funções concedidas ao usuário associado.

  Exemplo

  Para DELETE um host, o usuário que possui a chave de API usada para fazer a solicitação deve ser um Project Monitoring Admin ou Project Owner no projeto ao qual o host pertence.

• Muitos recursos estão vinculados a um projeto (anteriormente conhecido como grupo), conforme evidenciado pelas URLdo seguinte formato:

  /api/public/v1.0/groups/{PROJECT-ID}/

  Para estes recursos, o usuário vinculado à chave de API deve ser um membro do projeto ou deve ser atribuído a uma das funções GLOBAL . Caso contrário, o aplicativo do Ops Manager responde com um erro HTTP 401.

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 Ops Manager. A configuração de automação é onde você descreve e configura os processos MongoDB a serem implementados. O Ops Manager refere-se a isso como o "estado do objetivo" 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.

Informações adicionais

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