Docs Menu

Docs HomeAtlas App Services

Atlas Data API

On this page

  • Endpoints
  • Supported Environments
  • Data Formats

The Atlas Data API is a secure, serverless HTTPS API that lets you work with data stored in a linked data source or run custom application logic. You don't need to install any database drivers or opinionated libraries to work with the Data API. Instead, you send requests like this from an HTTPS client:

curl -X POST \
https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello \
-H 'apiKey: <API Key>' \
-H 'Content-Type: application/json' \
-d '{ "message": "Hello, world!" }'

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 client apps. For each incoming request, the Data API authenticates the calling user, authorizes the request, runs the endpoint logic, and then returns an HTTPS response to the caller.

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 functions that you write. You can use custom endpoints to run your app's backend logic or as webhooks that integrate with external services.

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

You can call the Data API from most HTTP clients. Supported environments include:

  • Serverless functions

  • Mobile applications

  • Servers

  • Internet of things devices

You cannot call the Data API from a web browser or any other client that enforces the CORS protocol. Atlas provides alternative methods to query MongoDB from the web browser:

Note

Atlas App Services does not currently support private endpoints.

MongoDB stores data in a format called BSON, which is similar to a JSON object in structure but supports additional data types and uses a binary encoding. BSON is efficient for computers but is not human readable so you can't work with it directly.

Instead, the Data API uses two formats to represent data in requests and responses:

  • The JSON format uses standard types that any tool can parse and understand. However, JSON cannot represent all BSON types so JSON responses may lose type information for some fields. For example, BSON has distinct types for 32-bit integers and 64-bit floats but a JSON response represents both as a number.

  • The EJSON format, short for MongoDB Extended JSON, is a superset of standard JSON that uses structured fields to represent BSON data that don't have corresponding JSON types. This fully represents your data but requires your client to understand how to work with EJSON.

Example

The following document shows BSON types represented in JSON and EJSON:

You define a single default return type for all generated Data API endpoints and individually for each custom endpoint. Incoming requests can also specify a preferred data format that overrides the default using an Accept header.

The following table compares the JSON and EJSON representations of each supported type:

Type
EJSON
JSON
Array
[ <elements> ]
[ <elements> ]
Binary
{
"$binary": {
"base64": "e67803a39588be8a95731a21e27d7391",
"subType": "05"
}
}
{
"Subtype": 5,
"Data": "e67803a39588be8a95731a21e27d7391"
}
Date
{
"$date": {
"$numberLong": "1641954803067"
}
}
"2022-01-12T02:33:23.067Z"
Decimal128
{ "$numberDecimal": "9823.1297" }
"9823.1297"
Document
{ <content> }
{ <content> }
Double
{
"$numberDouble": "10.5"
}
10.5
Int32
{"$numberInt":"10"}
10
Int64
{"$numberLong":"50"}
50
MaxKey
{ "$maxKey": 1 }
{}

No JSON equivalent

MinKey
{ "$minKey": 1 }
{}

No JSON equivalent

ObjectId
{
"$oid":"5d505646cf6d4fe581014ab2"
}
"5d505646cf6d4fe581014ab2"
Regular Expression
{
"$regularExpression": {
"pattern":"^H",
"options":"i"
}
}
{
"Pattern": "^H",
"Options": "i"
}
Timestamp
{
"$timestamp": {
"t":1565545664,
"i":1
}
}
{
"T": 1565545664,
"I": 1
}
←  Run GraphQL Operations from a CLIData API Endpoints →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.