Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services

Atlas Data API

On this page

  • Endpoints
  • How the Data API Works
  • When to Use the Data API
  • Constraints

The Data API is a managed service that lets you securely work with data stored in Atlas using standard HTTPS requests. The Data API is not a direct connection to your database. Instead, the API is a fully-managed middleware service that sits between your cluster and the clients that send requests.

You can use the Data API to connect to MongoDB Atlas from any platform that supports HTTPS, including:

  • Web browsers

  • Web servers

  • CI/CD pipelines

  • Serverless & Edge compute environments

  • Mobile applications

  • Internet-Of-Things devices

You don't need to install any database drivers or opinionated libraries to work with the Data API. Instead, you send standard HTTPS requests like the following:

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne" \
  -X POST \
  -H "Content-Type: application/ejson" \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "hello",
    "document": {
      "text": "Hello, world!"
    }
  }'
{ "insertedId": "63dc56ac74ddb86ed3eb8474" }

Endpoints

The Data API supports two types of endpoints:

  • Data API Endpoints are automatically generated endpoints that each represent a MongoDB operation. You can use the endpoints to create, read, update, delete, and aggregate documents in a MongoDB data source.

    To learn more, including how to set up and call endpoints, see Data API Endpoints.

  • Custom Endpoints are app-specific API routes handled by Atlas Functions that you write. You can use custom endpoints to define operations that fit your use case specifically. For example, you could create an endpoint that runs a pre-defined aggregation or that integrates with an external webhook service.

    To learn more, including how to create and call endpoints, see Custom HTTPS Endpoints.

How the Data API Works

Data API requests may resemble traditional database operations, like find or insertOne, but the Data API is not a direct connection to your database. Instead, the Data API adds additional authentication, authorization, and correctness checks to ensure that your data is only accessed or modified in the ways you allow. This allows you to safely access data in Atlas from potentially vulnerable clients like web apps.

For each incoming request, the Data API:

  1. Authenticates the calling user. This might involve validating an access token, logging in with header credentials, or directly assigning a specific runtime user based on your configuration.

  2. Authorizes the request. This ensures that the user sent a well-formed request and has permission to perform the requested operation based on your endpoint authorization scheme.

  3. Runs the requested operation. This might involve reading or writing data in Atlas with a generated endpoint or invoke a custom function that you wrote.

    For requests that read or write data in Atlas, the Data API also enforces the access control rules and document schemas defined in your App. This means that users can only access data they're allowed to read and write. Requests fail if they include an invalid write operation.

  4. Returns an HTTPS response to the caller. The response includes the result of a generated endpoint operation or any data that you return from a custom endpoint. In the request, you can choose to receive the response in either JSON or EJSON format.

When to Use the Data API

For server applications, and especially for high-load and latency sensitive use-cases, we recommend connecting directly to Atlas with a MongoDB driver. Operations called through a Data API endpoint take longer to complete than the corresponding MongoDB operations called through a driver. Additionally, the drivers provide more flexibility and control over how your operations are executed. To learn more, visit the MongoDB Drivers documentation.

We recommend using the Data API when:

  • You want to run MongoDB operations from a web application or other client that you can't trust.

  • You can't or don't want to manage a MongoDB driver in your server-side environment. For example, some edge compute environments don't support database drivers or connection pooling.

  • You want to develop a new feature and prefer a flexible solution for working on the client side first before later creating and refining the API layer.

  • You want to integrate Atlas data access into a federated API gateway.

  • You want to connect to App Services from an environment not currently supported by an Atlas Device SDK and don't want to use a driver to connect over the wire protocol.

Constraints

The following constraints apply to Data API requests and responses:

  • Requests will time out after 300 seconds of runtime.

  • Data API response payloads are limited to 350 MB in size.

Back

Monitor Edge Server

Next

Data API Endpoints

On this page