Referencia de la API de administración de Atlas

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 y convenciones:

• Encabezado de solicitud de tipo de contenido

  Al enviar JSON al servidor a través POST de o,PUT asegúrese de especificar el encabezado de solicitud de tipo de contenidoContent-Type: application/json correcto:.

• Campos inválidos

  Los campos no válidos se rechazan en lugar de ignorarse. Por ejemplo, si intentas crear una nueva entidad y escribes mal uno de los campos, o intentas actualizar una entidad existente e incluyes un campo que no se puede modificar, el servidor responde con un código de estado 400 y un mensaje de error que indica qué campo no es válido.

• Fechas con formato ISO-8601

  Todas las fechas se devuelven como cadenas con formato ISO-8601designadas en UTC. Al enviar fechas al servidor (es decir, como parámetros de consulta o campos en entidades de solicitud POST PATCH o), utilice fechas con formato8601ISO-. Si no especifica una zona horaria, se asume que es UTC. Sin embargo, se recomienda encarecidamente incluir un indicador de zona horaria para evitar ambigüedades.

• Marcas de tiempo BSON

  En algunos casos, una marca de tiempo se devuelve como una marca de tiempo BSON, sobre todo en los recursos de copia de seguridad. Estos se representan en documentos JSON como un objeto con dos campos:, date que es una8601cadena de fecha con formato ISO- en UTC con granularidad al segundo, y,increment un 32entero de bits.

• Nombres de campos para campos con números

  Los campos que contienen valores numéricos en una unidad particular se nombrarán de manera de eliminar la ambigüedad de la unidad utilizada.

• Campos vacíos

  Los campos que no tienen un valor actual se devuelven con un valor por defecto apropiado.

  Se omiten los campos que no tienen un valor por defecto razonable en la entidad.

• Orden de campos

  Los campos de los documentos JSON devueltos por el servidor no siguen un orden específico y este puede cambiar. No dependa del orden de los campos.

Enlace

Cada recurso incluye uno o más enlaces a subrecursos 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, solo incluye la self relación de enlace.

Para obtener más información, consulte la Especificación de Enlaces Web. Tenga en cuenta que, si bien la especificación describe un formato para incluir enlaces en los encabezados de respuesta HTTP, no es obligatorio. Para facilitar la navegación por la API de Administración de Atlas, se incluyen los enlaces en el cuerpo de la respuesta en lugar de en los encabezados.

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 los siguientes parámetros de consulta:

La entidad de respuesta contiene tres campos:

Si solicita una lista de entidades y no obtiene resultados, la API de administración de Atlas responde con un 200 código de estado y la results matriz está vacía. 404 En este caso, no responde con un, ya que la lista de entidades podría no estar vacía en el futuro. Sin embargo, si solicita una lista de entidades en un contexto inexistente (por ejemplo, la lista de hosts de un proyecto inexistente), la 404 respuesta sí es.

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 "sobre", que es simplemente una capa adicional de información en el documento JSON y contiene los detalles relevantes que normalmente se incluirían en los encabezados de respuesta. De forma predeterminada, la API de administración de Atlas no incluye la respuesta en un sobre. Para solicitarlo, simplemente agregue 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 solo agrega el campo status al sobre existente.

Formateo legible

De forma predeterminada, se eliminan los espacios en blanco superfluos del JSON devuelto por el servidor. Para solicitar un JSON con formato de impresión 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 "https://cloud.mongodb.com/api/atlas/v1.0?pretty=true"

Códigos de respuesta

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

Errors

Cuando una solicitud arroja un error, el cuerpo de la respuesta contiene un documento JSON. Este documento incluye detalles sobre por qué falló la solicitud de la API de administración de Atlas. El documento contiene 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
}

Identificación del proyecto

Su ID de proyecto es un valor de cadena que identifica de forma única un proyecto Atlas.

Los proyectos de Atlas se identificaban anteriormente como "grupos". Algunos puntos de conexión de Atlas hacen referencia a group o {GROUP-ID} como parte de la ruta de la solicitud, la consulta o los parámetros del cuerpo. Para cualquier punto de conexión que requiera su {GROUP-ID}, especifique su ID de proyecto.

Para recuperar el ID de su proyecto:

Autenticación

La API de administración de Atlas utiliza uno de dos métodos para autenticar las solicitudes: cuentas de servicio o claves de API. Esto garantiza que los tokens de acceso y las claves que sirven como nombres de usuario y contraseñas nunca se envíen a través de la red. Para obtener más información, consulte Métodos de autenticación de la API de administración de Atlas.

Para obtener detalles de uso, consulta realizar una solicitud de API.

Limitación de velocidad

Ciertos recursos limitan la cantidad de solicitudes que pueden procesar por minuto.

Para estos recursos, Atlas permite hasta 100 solicitudes por minuto por proyecto. Los métodos de autenticación de la API de administración de Atlas pertenecen a una organización, pero se les puede otorgar acceso a varios proyectos.

Si excede el límite de velocidad, la API de administración de Atlas devuelve un código de 429 estado HTTP (demasiadas solicitudes).

Próximos pasos

Para comenzar, consulte Introducción a la API de administración de Atlas.

Para gestionar el acceso programático a la API de Administración de Atlas, consulte cualquiera de los siguientes procedimientos:

• Gestiona el acceso programático a una organización.

• Gestiona el acceso programático a múltiples organizaciones.

• Administra el acceso programático a un proyecto.