Referencia de la API de administración de Atlas

Métodos HTTP

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

• Encabezado de solicitud de tipo de contenido

  Cuando envíe JSON al servidor a través de POST o PUT, asegúrese de especificar el tipo de contenido correcto en el encabezado de solicitud: Content-Type: application/json.

• Campos No Vá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 ISO-8601cadenas formateadas designadas en UTC. Al enviar fechas al servidor (es decir, como parámetros de query o campos en entidades de solicitud POST o PATCH), utiliza fechas con formato ISO-8601. Si no especifica una zona horaria, se asume UTC. Sin embargo, se recomienda encarecidamente que se incluya un designador de zona horaria para evitar cualquier ambigüedad.

• Marcas de tiempo BSON

  En algunos casos, se devuelve una marca de tiempo como un 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 un ISO-8601-formatted date string en UTC con una granularidad de hasta el segundo, y increment un entero de 32bits.

• Nombres de campos para campos con números

  Los campos que contienen valores numéricos en una unidad particular serán denominados de manera que se evite la ambigüedad sobre 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 en los documentos JSON devueltos por el servidor no tienen un orden particular y el orden puede cambiar. No dependas del orden de los campos.

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 un arreglo de objetos de relaciones de enlaces. Cada relación de enlace tiene dos campos:

Todas las entidades incluyen al menos una relación de enlace denominada self, que no es más que su propia URL. Cuando una entidad forma parte de una lista, solo se incluye la self relación de enlace.

Para obtener más información, consulta la especificación de enlace web. Tenga en cuenta que, aunque la especificación describe un formato para incluir enlaces en los encabezados de respuesta HTTP, esto no es un requisito. Para que la API de administración de Atlas sea fácilmente navegable, incluye los enlaces en el cuerpo de la respuesta en lugar de en los encabezados de la respuesta.

Listas

Algunos recursos devuelven una lista de entidades. Cuando se espera una lista de entidades en una respuesta, los resultados se devuelven en tandas delimitadas por los siguientes parámetros de query:

La entidad de respuesta contiene tres campos:

Si realizas una solicitud para una lista de entidades y no hay resultados, la API de administración de Atlas responde con un código de estado 200 y el arreglo results está vacío. No responde con un 404 en este caso, ya que la lista de entidades podría no estar vacía en algún punto en el futuro. Sin embargo, si solicita una lista de entidades en un contexto que no existe (por ejemplo, la lista de hosts de un proyecto inexistente), ésto sí resulta en un estado de respuesta 404.

Sobres

Algunos clientes podrían no poder acceder a los encabezados de respuesta HTTP y/o al código de estado. En ese caso, puedes solicitar que la respuesta incluya un "sobre", que simplemente es una capa adicional de información en el documento JSON y contiene cualquier detalle relevante que normalmente se encontraría en los encabezados de respuesta. Por defecto, la API de administración de Atlas 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 respuestas que contienen una lista de entidades, ya existe un sobre que envuelve los resultados, por lo que especificar envelope=true solo añade el campo status al sobre existente.

Formateo legible

Por defecto, los espacios innecesarios se eliminan del JSON devuelto por el servidor. Para solicitar un JSON con buena presentación, simplemente agrega el parámetro de query pretty=true a cualquier solicitud:

curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \
  --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 estándar de HTTP, incluyendo:

Errors

Cuando una solicitud devuelve 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
}

ID del proyecto

Tu ID del grupo es un valor de string que identifica un Proyecto Atlas de manera exclusiva.

Los proyectos de Atlas se identificaban anteriormente como "grupos". Algunos endpoints de Atlas hacen referencia a group o {GROUP-ID} como parte de la ruta de solicitud, los parámetros de query o de cuerpo. Para cualquier endpoint que requiera tu {GROUP-ID}, especifica tu ID del grupo en su lugar.

Para recuperar el ID del grupo:

Autenticación

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

Para detalles de uso, consulta Realiza una solicitud de API.

Limitación de tasa

Atlas utiliza limitación de tasa para controlar la tasa de solicitudes enviadas a los puntos finales de la V2 API dentro de un período de tiempo especificado, para evitar la sobrecarga y garantizar un uso justo. Atlas utiliza el algoritmo Token Bucket para limitar la cantidad de solicitudes que procesa. Para obtener más información, consulte Límites de velocidad de la API de administración de Atlas.

Próximos pasos

Para comenzar, consulta Empezar con 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.