Endpoints da Data API [obsoletos]

Autenticação

Os pontos de conexão da API de dados são executados no contexto de um usuário específico, o que permite à sua aplicação impor regras e validar esquemas de documento para cada um solicitação.

Por padrão, os endpoints usam a Autenticação de Aplicativo, que exige que cada solicitação inclua credenciais para um dos usuários do aplicativo, como uma chave API ou JWT. Você também pode configurar outros esquemas de autenticação personalizados para atender às necessidades do seu aplicativo.

Para ver exemplos de como autenticar solicitações, consulte Autenticar Solicitações de API de Dados.

{
  "run_as_user_id": "628e47baf4c2ac2796fc8a91"
}

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

Autorização

Você pode exigir que os usuários autenticados forneçam informações de autorização adicionais em cada solicitação. Você define o esquema de autorização para todos os endpoints de API de dados gerados em sua configuração da API de dados.

Os endpoints oferecem suporte nativo a um conjunto de esquemas de autorização internos que usam uma string secreta para provar que a solicitação está autorizada. Você também pode definir um esquema de autorização personalizado que pode ser usado junto com os esquemas integrados ou em vez deles.

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

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

Tipo de resposta

Os endpoints podem retornar dados em um dos dois formatos de dados, JSON ou EJSON.

Por padrão, os endpoints retornam JSON, que é um formato de dados padrão que é amplamente suportado em linguagens e plataformas modernas. No entanto, JSON não pode representar todos os tipos de dados que você pode armazenar no MongoDB e perde informações de tipo para alguns tipos de dados.

Você também pode configurar pontos de conexão para retornar EJSON, que usa objetos JSON estruturados para representar totalmente os tipos suportados pelo MongoDB. Isso preserva informações de tipo nas respostas, mas exige que seu aplicativo entenda como analisar e usar EJSON.

{
   "return_type": "JSON"
}

{
   "return_type": "EJSON"
}

Permissões de acesso

O Data API usa as regras de acesso a dados da sua aplicação para determinar se um usuário pode ler e gravar dados. Para permitir que as solicitações do Data API acessem uma coleção específica, você deve primeiro definir regras para a coleção.

Você também pode configurar uma Lista de Acesso IP para segurança adicional.

Versões da API

O Data API usa um esquema de controle de versão interno para atualizar os endpoints ao longo do tempo, mantendo a compatibilidade com versões anteriores. As solicitações de entrada podem especificar qual versão de um endpoint usar na URL de solicitação e o Data API pode servir qualquer versão que você tenha habilitado.

Você deve habilitar uma nova versão antes que os usuários possam chamar pontos de conexão com essa versão. Você sempre pode habilitar a versão mais recente da API de dados. No entanto, você não pode habilitar uma versão mais antiga depois que uma versão mais recente tiver sido lançada.

As seguintes versões são atualmente suportadas:

• beta

• v1

Escolha uma versão da API

As solicitações de API de dados especificam qual versão da API usar na URL da solicitação. Uma solicitação pode especificar qualquer versão que esteja habilitada para sua aplicação.

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

Especificar o Formato dos Dados da Solicitação

As solicitações do Data API devem incluir um cabeçalho Content-Type para especificar o formato de dados usado no corpo da solicitação.

• Utilize Content-Type: application/json para representar tipos JSON padrão em um corpo de solicitação da API de dados.

• Utilize Content-Type: application/ejson para representar tipos de JSON padrão e tipos de EJSON adicionais em um corpo de solicitação de API de dados.

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 }

Escolher um Formato de Dados de Resposta

Uma solicitação pode incluir um cabeçalho Accept para solicitar um formato de dados específico para o corpo da resposta, seja JSON ou EJSON. Se uma solicitação não incluir um cabeçalho Accept válido, a resposta usará o formato de dados especificado em sua configuração da Data API.

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 a Solicitação

Se um ponto de extremidade estiver configurado para usar a autenticação de aplicativo, você deve incluir um token de acesso de usuário válido ou credenciais de login com cada solicitação.

Em geral, a autenticação de portador com um token de acesso tem uma taxa de transferência mais alta e é mais segura do que os cabeçalhos de credenciais. Use um token de acesso em vez de cabeçalhos de credenciais quando possível. O token permite que você execute várias solicitações sem autenticar o usuário novamente. Ele também permite que você envie solicitações de um navegador da Web que imponha o CORS.

Para usar um token de acesso, primeiro autentique o usuário por meio de um fornecedor de autenticação do App Services. Em seguida, obtenha o token de acesso retornado pelo App Services e inclua-o no cabeçalho de autorização da solicitação usando um esquema de token de portador. Para obter mais informações sobre como adquirir e usar um token de acesso, consulte Autenticação 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"
    }
  }'

Como alternativa, você pode incluir credenciais de login válidas para o usuário nos cabeçalhos de solicitação.

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 a Solicitação

Dependendo da configuração de autorização da Data API, suas solicitações podem precisar incluir informações adicionais de autorização.

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" }
  }'