Principios de las API públicas

HTTP Methods

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

JSON

Todos los elementos están representados en JSON. Se aplican las siguientes reglas para las solicitudes y convenciones de respuesta:

Enlace

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

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

Todas las entidades incluyen al menos una relación de enlace llamada self, 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 relación de enlace 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 obtener más información, consulte la especificación de enlace 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 query:

La entidad de respuesta contiene tres campos:

Si se solicita una lista de entidades y no se obtienen resultados, la API responde con un código de estado HTTP 200 y una matriz results vacía. En este caso,no responde con un código 404, ya que la lista de entidades podría no estar vacía en algún momento posterior.

Si hubieras solicitado una lista de entidades en un contexto que no existe (es decir, la lista de hosts para un proyecto inexistente), entonces esto resultaría en un estado de respuesta 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
}

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 un envelope, que es simplemente una capa adicional de información en el documento JSON que contiene los detalles relevantes que normalmente se incluirían en los encabezados de respuesta.

Por defecto, la API no incluye la respuesta en un sobre. Para solicitarlo, simplemente agregue el parámetro de consulta envelope=true.

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

Para las respuestas que contiene una lista de entidades, ya existe una envoltura que envuelve los resultados, así que especificar envelope=true como un query en este caso sólo agrega el campo status al sobres actual.

Formateo legible

Por defecto, los espacios en blanco innecesarios se eliminan del JSON que devuelve Ops Manager. Para solicitar un JSON con formato legible, simplemente agregue el parámetro de consulta pretty=true a cualquier solicitud:

curl --user '{PUBLIC-KEY}:{PRIVATE-KEY}' --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 da lugar a un error, el cuerpo de la respuesta contiene un documento JSON con información adicional sobre lo que salió mal. 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, el Ops Manager API usa HTTP Digest autenticación. Los detalles de la autenticación por resumen están más allá del alcance de este documento, pero esencialmente requiere un nombre de usuario y una contraseña que son encriptada utilizando un valor único generado por el servidor llamado nonce. El nombre de usuario corresponde al nombre de usuario de una cuenta registrada en Ops Manager, y la contraseña es una llave pública de API asociada a esa cuenta.

Tenga en cuenta los siguientes puntos:

• El nonce generado por el servidor es utilizado por el cliente para encriptar el nombre de usuario y la contraseña antes de enviarlos de regreso al servidor para autenticar una solicitud. El nonce solo es válido por una corta cantidad de tiempo según la especificación de autenticación por resumen. Esto se hace para evitar ataques de reproducción, por lo que no se puede almacenar en caché un nonce y utilizarlo 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 tiene el concepto de roles, que permiten un control más detallado sobre las operaciones que un usuario puede realizar. Los recursos de la API también hacen cumplir las mismas reglas de autorización, por lo que los recursos y métodos a los que se puede acceder con una clave de API se rigen por los roles otorgados al usuario asociado.

  Ejemplo

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

• Muchos recursos están vinculados a un proyecto (anteriormente conocido como grupo), tal como lo demuestran las URLdel formulario siguiente:

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

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

Automatización

El recurso Configuración de automatización y los recursos Obtener el estado de automatización del plan más reciente proporcionan endpoints que permiten modificar la implementación de un proyecto y recuperar el estado de la implementación. Puedes modificar una implementación enviando una nueva configuración de automatización a Ops Manager. La configuración de la automatización es donde se describen y configuran los procesos de MongoDB que se van a implementar. Ops Manager se refiere a esto como el 'estado objetivo' de la implementación. Cuando envías 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.