Público Principios de laAPI

MétodosHTTP

Todos los recursos admiten un subconjunto de estos métodos HTTP comunes:

JSON

Todas las entidades se representan en JSON. Se aplican las siguientes reglas para solicitudes y convenciones de respuesta:

Enlace

Cada recurso incluye uno o más enlaces a subrecursos y/o recursos relacionados.

Los enlaces se colocan en el campo links de una entidad, que es una matriz de objetos de relación de enlace. Cada relación de enlace tiene dos campos:

Todas las entidades incluyen al menos una relación de enlace self llamada, que es simplemente su propia URL. Cuando una entidad forma parte de una lista (es decir, al solicitar todos los hosts de un proyecto), solo incluye la self relación de enlace.

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 obtener más información, consulte la Especificación de enlaces web.

Listas

Algunos recursos devuelven una lista de entidades.

Cuando se espera una lista de entidades en una respuesta, los resultados se devuelven en lotes delimitados por dos parámetros de consulta:

La entidad de respuesta contiene tres campos:

Si solicitas una lista de entidades y no hay resultados, la API responde con un HTTP código de estado 200 y un results arreglo vacío. No responde con un 404 en este caso, ya que la lista de entidades puede no estar vacía en el futuro.

Si ha solicitado una lista de entidades en un contexto que no existe (es decir, la lista de hosts de un proyecto inexistente), esto genera un 404 estado de respuesta HTTP.

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
}

Sobres

Es posible que algunos clientes no puedan acceder a los encabezados de respuesta HTTP ni al código de estado. En ese caso, puede solicitar que la respuesta incluya envelope un, que es simplemente una capa adicional de información en el documento JSON que contiene los detalles relevantes que normalmente se encontrarían en los encabezados de respuesta.

De forma predeterminada, la API no incluye la respuesta en un sobre. Para solicitarlo, simplemente añada el parámetro de envelope=true consulta.

Para las respuestas que contienen una sola entidad, el sobre contiene dos campos:

Para las respuestas que contienen una lista de entidades, ya existe un sobre que envuelve los resultados, por lo que especificar envelope=true como parámetro de consulta en este caso solo agrega el campo status al sobre existente.

Formateo legible

De forma predeterminada, se eliminan los espacios en blanco superfluos del JSON que devuelve Ops Manager. Para solicitar un JSON con formato preimpreso, simplemente añada el pretty=true parámetro de consulta a cualquier solicitud:

curl --user '{USERNAME}:{APIKEY}' --digest \
--header 'Accept: application/json' \
--include \
--request GET "{opsManagerHost}:{Port}/api/public/v1.0?pretty=true"

Códigos de respuesta

Las respuestas utilizan los códigos de respuesta HTTP estándar, incluidos:

Errors

Cuando una solicitud genera un error, el cuerpo de la respuesta contiene un documento JSON con detalles adicionales sobre el problema. El documento contiene 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 la lista de códigos, consulte Códigos de error de la API de administración de Ops Manager.

Autenticación

Como se mencionó anteriormente, la API de Ops Manager utiliza autenticación HTTP Digest. Los detalles de la autenticación digest quedan fuera del alcance de este documento, pero básicamente requiere un nombre de usuario y una contraseña, cuyo hash se basa en un valor único generado por el servidor, denominado nonce. El nombre de usuario corresponde al de una cuenta registrada de Ops Manager y la contraseña es una clave API pública asociada a dicha cuenta.

Tenga en cuenta los siguientes puntos:

• El cliente utiliza el nonce generado por el servidor para cifrar el nombre de usuario y la contraseña antes de enviarlos de vuelta al servidor para autenticar una solicitud. El nonce solo es válido durante un breve periodo, según la especificación de autenticación de resumen. Esto sirve para evitar ataques de repetición, por lo que no se puede almacenar en caché un nonce y usarlo indefinidamente.

• Algunos métodos de recursos exigen mayor seguridad y están protegidos adicionalmente por listas de acceso que permiten el acceso al recurso solo desde las direcciones IP enumeradas. Cada usuario configura su propia lista de direcciones IP que permite el acceso al recurso.

• La aplicación Ops Manager utiliza un concepto de roles que permite un control más preciso de las operaciones que un usuario puede realizar. Los recursos de la API también aplican las mismas reglas de autorización, por lo que los recursos y métodos a los que se puede acceder mediante una clave de API se rigen por los roles asignados al usuario asociado.

  Ejemplo

  Para DELETE un host, el usuario que posee la clave API utilizada para realizar la solicitud debe ser un Project Monitoring Admin o Project Owner un en el proyecto al que pertenece el host.

• Muchos recursos están vinculados a un proyecto (antes conocido como grupo), como lo evidencian las URLcon el siguiente formato:

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

  Para estos recursos, el usuario vinculado a la clave API debe ser miembro del proyecto o tener asignado uno de los GLOBAL roles. De lo contrario, la aplicación Ops Manager responde con un 401 error HTTP.

Automatización

Los recursos "Recurso de configuración de automatización" y "Obtener el estado de automatización del último plan" proporcionan puntos finales que permiten modificar la implementación de un proyecto y recuperar su estado. Puede modificar una implementación enviando una nueva configuración de automatización a Ops Manager. La configuración de automatización es donde se describen y configuran los procesos de MongoDB que se implementarán. Ops Manager se refiere a esto como el "estado objetivo" de la implementación. Al enviar una nueva configuración de automatización a través de la API, las automatizaciones ajustan el estado actual del sistema para que coincida con el estado objetivo.

Información Adicional

Consulte Recursos de la API de administración de Ops Manager para obtener una referencia completa de todos los recursos disponibles en la API pública de Ops Manager.