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 de POST o PUT, asegúrate de especificar el encabezado de solicitud del tipo de contenido correcto: 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 los documentos JSON como un objeto con dos campos: date, que es una string de fecha formateada ISO-8601en UTC con granularidad al 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 de los documentos JSON que devuelve el servidor no siguen ningún orden en particular, y el orden puede cambiar. No depender 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 llamada self, que simplemente es su propia URL. Cuando una entidad forma parte de una lista, entonces solo incluye la relación de vínculo self.

Para más información, consulte la Especificación de Vinculación Web. Nota que, aunque la especificación describe un formato para incluir enlaces en los encabezados de respuesta HTTP, no es obligatorio hacerlo. Para que la API de administración de Atlas sea fácilmente navegable, esta 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

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 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 en blanco innecesarios se eliminan del JSON devuelto por el servidor. Para solicitar un JSON con formato bonito, simplemente añada 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 HTTP, incluyendo:

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
}

ID 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 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 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 tasa

Atlas utiliza la limitación de velocidad para controlar la frecuencia de las solicitudes enviadas a los puntos finales de2 la API V dentro de un plazo específico 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.