Público API Principles

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 por lo menos una relación de enlace llamada self, que es simplemente su propia URL. Cuando una entidad forma parte de una lista (por ejemplo, al solicitar todos los hosts en un proyecto), sólo incluye la relación de enlace 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 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 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 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 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.

Por defecto, la API no incluye la respuesta en un sobre. Para solicitar uno, simplemente añade el parámetro de query 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

De forma predeterminada, el espacio en blanco innecesario se elimina del JSON que Cloud Manager devuelve. Para pedir un JSON con formato legible, simplemente puedes añadir el parámetro de query pretty=true a cualquier solicitud:

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 respuesta

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

Errors

Cuando una solicitud resulta en un error, el cuerpo de la respuesta contiene un documento JSON con detalles adicionales 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, consulta Códigos de error de la API de administración de Cloud Manager.

Autenticación

El API Cloud Manager utiliza uno de dos métodos para autenticar las solicitudes: claves API o cuentas de servicio. Esto garantiza que las claves y los tokens de acceso que sirven como nombres de usuario y contraseñas nunca se envíen a través de la red. Para conocer los detalles de uso, consulte Acceso programático a Cloud Manager con una cuenta de servicio.

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.

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. Puede modificar una implementación enviando una nueva configuración de automatización a Cloud Manager. La configuración de la automatización es donde se describen y configuran los procesos de MongoDB que se van a implementar. Cloud 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.

Limitación de tasa

Ciertos recursos están sujetos a limitaciones de velocidad.

Para recursos con límite de velocidad, Cloud Manager permite hasta 100 solicitudes por minuto por proyecto. Tenga en cuenta que se asigna una clave API pública a cada usuario de Cloud Manager, pero este puede acceder a varios proyectos.

Si excedes el límite de velocidad, la API devuelve un código de respuesta HTTP 429 Too Many Requests.

Información Adicional

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