Puntos finales de la API de datos

Autenticación

Los puntos finales de la API de datos se ejecutan en el contexto de un usuario específico, lo que permite que su aplicación aplique reglas y valide esquemas de documentos para cada solicitud.

De forma predeterminada, los endpoints utilizan la autenticación de aplicaciones, que requiere que cada solicitud incluya las credenciales de uno de los usuarios de la aplicación, como una clave API o JWT. También puede configurar otros esquemas de autenticación personalizados para adaptarlos a las necesidades de su aplicación.

Para obtener ejemplos de cómo autenticar solicitudes, consulte Autenticar solicitudes de API de datos.

{
  "run_as_user_id": "628e47baf4c2ac2796fc8a91"
}

[
  {
    ...,
    "run_as_user_id_script_source": "exports = () => {return \"628e47baf4c2ac2796fc8a91\"}"
  }
]

Autorización

Puede exigir a los usuarios autenticados que proporcionen información de autorización adicional en cada solicitud. El esquema de autorización para todos los puntos finales de la API de datos generados se define en la configuración de la API de datos.

Los endpoints admiten de forma nativa un conjunto de esquemas de autorización integrados que utilizan una cadena secreta para demostrar que la solicitud está autorizada. También puede definir un esquema de autorización personalizado que pueda usar junto con los esquemas integrados o en lugar de ellos.

[
  {
    ...,
    "verification_method": "SECRET_AS_QUERY_PARAM",
    "secret_name": "secret_verification_string"
  }
]

{
  ...,
  "can_evaluate": {
    "%%request.requestHeaders.x-secret-key": "my-secret"
  }
}

Tipo de respuesta

Los puntos finales pueden devolver datos en uno de dos formatos de datos, JSON o EJSON.

De forma predeterminada, los endpoints devuelven JSON, un formato de datos estándar ampliamente compatible con lenguajes y plataformas modernas. Sin embargo, JSON no puede representar todos los tipos de datos que se pueden almacenar en MongoDB y, en algunos casos, pierde información de tipo.

También puede configurar puntos finales para que devuelvan EJSON, que utiliza objetos JSON estructurados para representar completamente los tipos compatibles con MongoDB. Esto conserva la información de tipo en las respuestas, pero requiere que su aplicación comprenda cómo analizar y usar EJSON.

{
   "return_type": "JSON"
}

{
   "return_type": "EJSON"
}

Permisos de acceso

La API de datos utiliza las reglas de acceso a datos de tu aplicación para determinar si un usuario puede leer y escribir datos. Para permitir que las solicitudes de la API de datos accedan a una colección específica, primero debes definir las reglas para dicha colección.

También puede configurar una lista de acceso IP para mayor seguridad.

Versiones de API

La API de datos utiliza un sistema de control de versiones integrado para actualizar los endpoints con el tiempo, manteniendo la compatibilidad con versiones anteriores. Las solicitudes entrantes pueden especificar la versión de un endpoint que se usará en la URL de la solicitud, y la API de datos puede procesar cualquier versión que tenga habilitada.

Debe habilitar una nueva versión para que los usuarios puedan llamar a los endpoints con esa versión. Siempre puede habilitar la versión más reciente de la API de datos. Sin embargo, no puede habilitar una versión anterior después de que se haya publicado una versión más reciente.

Actualmente se admiten las siguientes versiones:

• beta

• v1

Elija una versión de API

Las solicitudes de API de datos especifican la versión de la API que se usará en la URL de la solicitud. Una solicitud puede especificar cualquier versión habilitada para la aplicación.

https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>

Especifique el formato de los datos de la solicitud

Las solicitudes de API de datos deben incluir un Content-Type encabezado para especificar el formato de datos utilizado en el cuerpo de la solicitud.

• Utilice Content-Type: application/json para representar tipos JSON estándar en un cuerpo de solicitud de API de datos.

• Utilice Content-Type: application/ejson para representar tipos JSON estándar y tipos EJSON adicionales en un cuerpo de solicitud de API de datos.

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/ejson' \
  -H 'Accept: application/ejson' \
  --data-raw '{
      "dataSource": "mongodb-atlas",
      "database": "learn-data-api",
      "collection": "hello",
      "document": {
        "_id": { "$oid": "629971c0d71aad65bd59c595" },
        "greeting": "Hello, EJSON!",
        "date": { "$date": { "$numberLong": "1654589430998" } }
      }
  }'

{ "insertedId": { "$oid": "629971c0d71aad65bd59c595" } }

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/updateOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "filter": { "greeting": "Hello, world!" },
     "update": {
         "$set": { "greeting": "Hello, universe!" }
     }
  }'

{ "matchedCount": 1, "modifiedCount": 1 }

Elija un formato de datos de respuesta

Una solicitud puede incluir un Accept encabezado para solicitar un formato de datos específico para el cuerpo de la respuesta, ya sea JSON o EJSON. Si una solicitud no incluye un Accept encabezado válido, la respuesta utiliza el formato de datos especificado en la configuración de la API de datos.

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/ejson' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": { "$oid": "629971c0d71aad65bd59c545"},
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": "629971c0d71aad65bd59c545",
  "greeting": "Hello, Leafie!",
  "date": "2022-06-07T08:10:30.998Z"
}

Autenticar la solicitud

Si un punto final está configurado para usar la autenticación de aplicaciones, debe incluir un token de acceso de usuario válido o credenciales de inicio de sesión con cada solicitud.

En general, la autenticación de portador con un token de acceso ofrece mayor rendimiento y es más segura que los encabezados de credenciales. Utilice un token de acceso en lugar de encabezados de credenciales siempre que sea posible. El token permite ejecutar múltiples solicitudes sin tener que volver a autenticar al usuario. También permite enviar solicitudes desde un navegador web que implemente CORS.

Para usar un token de acceso, primero autentique al usuario mediante un proveedor de autenticación de App Services. Luego, obtenga el token de acceso devuelto por App Services e inclúyalo en el encabezado de autorización de la solicitud mediante un esquema de token de portador. Para obtener más información sobre cómo adquirir y usar un token de acceso,consulte Autenticación de token de portador.

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

Otra opción es incluir credenciales de inicio de sesión válidas para el usuario en las cabeceras de la solicitud.

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteWFwcC1hYmNkZSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJleHAiOjIxNDU5MTY4MDB9.E4fSNtYc0t5XCTv3S8W89P9PKLftC4POLRZdN2zOICI" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

Autorizar la solicitud

Dependiendo de la configuración de autorización de su API de datos, es posible que sus solicitudes deban incluir información de autorización adicional.

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne?secret=12345 \
  -H "Content-Type: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'

Endpoint-Signature: sha256=<hex encoded hash>

/**
 * Generate an HMAC request signature.
 * @param {string} secret - The secret validation string, e.g. "12345"
 * @param {object} body - The endpoint request body e.g. { "message": "MESSAGE" }
 * @returns {string} The HMAC SHA-256 request signature in hex format.
 */
exports = function signEndpointRequest(secret, body) {
  const payload = EJSON.stringify(body);
  return utils.crypto.hmac(payload, secret, "sha256", "hex");
};

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H "Content-Type: application/json" \
  -H "Endpoint-Signature: sha256=769cd86855787f476afc8b0d2cf9837ab0318181fca42f45f34b6dffd086dfc7" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'