Read and Write with the Data API

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, the language you are using for your server does not have a driver.

• Your server-side code runs in an edge compute environment that does not 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 Atlas from an client not currently supported by a Realm SDK.

Atlas App Services

The Data API is powered by Atlas App Services.

You can quickly set up and access the Data API through Atlas, which creates an App Services App for you that's linked to the Atlas UI. The default configuration and Atlas UI support API key authentication with several basic permissions models.

You can define more complex API access permissions and customize your API with your own endpoints by modifying the underlying App that was created for you or enabling the API in your own App.

To learn more about App Services, how the Data API works, and how you can customize it, see Data API in the App Services documentation.

1. Enable the Data API

The Data API is disabled by default. To use the API, you need to turn it on in the Atlas UI for one or more clusters.

Click Data API in the left navigation menu. On the following screen, select one or more clusters that you want to enable the API on from the dropdown menu and then click Enable the Data API.

2. Create a Data API Key

The Data API uses project-level API keys to manage access and prevent unauthorized requests. Every request must include a valid Data API key.

A Data API key grants full read and write access every collection in a cluster and can access any enabled cluster in the project.

Click Create API Key, enter a unique name for the new key, and then click Create API Key.

You can now see and copy your new API key for the first and only time. Once you close the modal, Atlas will never expose the value again.

Copy the new API key and store it somewhere safe where you can reference it later. Data API keys are sensitive, so make sure not to hardcode them directly into user-facing apps or commit them to version control.

3. Send a Data API Request

You include your Data API key when you call action endpoints that read and write documents in MongoDB. For a list of all available actions & endpoints, see Data API Resources.

You can run the following commands in a shell to make sure everything works and then start exploring:

1. Insert a test document:

   curl --request POST \
     'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/v1/action/insertOne' \
     --header 'Content-Type: application/json' \
     --header 'apiKey: <Data API Key>' \
     --data-raw '{
         "dataSource": "<cluster name>",
         "database": "learn-data-api",
         "collection": "people",
         "document": {
           "name": "John Sample",
           "age": 42
         }
     }'

2. Then, find the test document that you just inserted:

   curl --request POST \
     'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/v1/action/findOne' \
     --header 'Content-Type: application/json' \
     --header 'apiKey: <Data API Key>' \
     --data-raw '{
         "dataSource": "<cluster name>",
         "database": "learn-data-api",
         "collection": "people",
         "filter": { "name": "John Sample" }
     }'

3. Finally, delete the test document:

   curl --request POST \
     'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/v1/action/deleteOne' \
     --header 'Content-Type: application/json' \
     --header 'apiKey: <Data API Key>' \
     --data-raw '{
         "dataSource": "<cluster name>",
         "database": "learn-data-api",
         "collection": "people",
         "filter": { "name": "John Sample" }
     }'

API Versions

The Data API uses a built-in versioning scheme to upgrade endpoints over time while maintaining backwards compatibility. Incoming requests can specify which version of an endpoint to use in the request URL and the Data API can serve any version that you have enabled.

You must enable a new version before users can call endpoints with that version. You can always enable the most recent Data API version. However, you cannot enable an older version after a newer version has been released.

The following versions are currently supported:

• beta

• v1

Data Access Permissions

The Atlas Data API allows you to define cluster-level read/write permissions that apply to all incoming requests. You can define one of the following for each cluster:

• Read and Write: Requests can read all data and can insert, modify, or delete data in any collection.

• Read Only: Requests can read all data in any collection but cannot write any data.

• No Access: Requests can't read or write any data in any collection.

For more complex permissions, you can define custom data access rules in the managed Atlas Data API app.

Authentication and API Keys

The Atlas Data API supports user authentication with API keys. Incoming requests must include an API key in a request header. You can create up to 100 Data API keys.

To allow users to authenticate requests with another method, like a username and password or a JSON web token, you can enable additional authentication providers in the App Services App.

Deployment Models & Regions

The App Services layer that runs the Data API processes requests on managed servers hosted in deployment regions around the world. You can control where you deploy your Data API and process requests using one of two deployment models:

• Global deployment hosts your API on servers in every supported region across the world. The API automatically routes and processes incoming requests to the server that's nearest to the requesting user.

• Local deployment hosts your API servers in one specific deployment region in AWS or Azure. The API processes all incoming requests in the local region.

  For a list of supported regions, see Deployment Models & Regions in the App Services docs.

Response Type

Endpoints can return data in one of two data formats, either JSON or EJSON.

By default, endpoints return JSON, which is a standard data format that is widely supported modern langauges and platforms. However, JSON cannot represent every data type that you can store in MongoDB and loses type information for some data types.

You can also configure endpoints to return EJSON, which uses structured JSON objects to fully represent the types that MongoDB supports. This preserves type information in responses but requires that your application understands how to parse and use EJSON.

Specify the Request Data Format

Data API requests must include a Content-Type header to specify the data format used in the request body.

• Use Content-Type: application/json to represent standard JSON types in a Data API request body.

• Use Content-Type: application/ejson to represent standard JSON types and additional EJSON types in a Data API request body.

Choose a Response Data Format

A request can include an Accept header to request a specific data format for the response body, either JSON or EJSON. If a request does not include a valid Accept header, the response uses the data format specified in your Data API configuration.

Authenticate Requests

To keep your data secure and correct, generated Data API endpoints always run in the context of a specific registered user.

Incoming requests must include request headers that authenticate a unique user for the request. There are two ways to authenticate: Bearer authentication and Credential authentication.

curl -X POST 'https://data.mongodb-api.com/app/<AppID>/endpoint/data/v1/action/find' \
   --header 'Authorization: Bearer <AccessToken>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "sample_mflix",
     "collection": "movies",
     "filter": {
       "title": "The Matrix"
     }
   }'