Custom HTTPS Endpoints

Base URL

Endpoints in an app share a base URL. The URL uses your App ID to uniquely point to your app.

Globally deployed apps use the following format:

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

Endpoints in a locally deployed app use a base URL specific to the app's deployment region (e.g. us-east-1)

https://<Region>.aws.data.mongodb-api.com/app/<App ID>/endpoint

Endpoint Routes

Every HTTPS endpoint has a route that serves as a name for the endpoint. An endpoint's route is arbitrary and specific to your app. However, it appears in the endpoint URL path and so should represent the action the route performs.

Route names must begin with a forward slash (/) and may contain additional forward slashes to indicate a nested path.

/my/nested/route

You call an endpoint by appending its route to your app's base URL and sending an HTTP request.

https://data.mongodb-api.com/app/<App ID>/endpoint/my/nested/route

HTTP Methods

Each endpoint in your app handles one or more HTTP methods for a given route. For example, you might have a single route that accepts POST requests to create a new resource and a GET request to list existing resources.

You can define multiple custom endpoints that serve the same route but handle different request methods. Alternatively, you can define a single endpoint for the route that handles all methods.

Custom endpoints support the following standard HTTP methods:

• GET

• POST

• PUT

• PATCH

• DELETE

Authentication

Custom endpoints run in the context of a specific user, which allows your app to enforce rules and validate document schemas for each request.

By default, endpoints use Application Authentication, which requires each request to include credentials for one of your application users, like an API key or JWT. You can also configure other custom authentication schemes to fit your application's needs.

For examples of how to authenticate requests, see Authenticate Data API Requests.

Authorization

An endpoint can require authenticated users to provide additional authorization information in the request. You define the authorization scheme for each custom endpoint by configuring the endpoint function.

Endpoints natively support a set of built-in authorization schemes that use a secret string to prove that the request is authorized. You can also define a custom authorization scheme that you can use together with or instead of the built-in schemes.

To learn how to configure authorization for a specific function, see Define a Function.

[
  {
     ...,
     "can_evaluate": {
       "%%request.headers.x-secret-key": "my-secret"
     }
  }
]

Access Request Data

A custom endpoint Request object represents the HTTP request that called the endpoint. You can access the incoming request's headers, query parameters, and body data.

{
  "headers": { "<Header>": ["<Header Value>"] },
  "query": { "<Query Parameter>": "<Parameter Value>" },
  "body": <BSON.Binary>
}

{
  "regions": "na&eu",
  "currency": "USD"
}

{
  "Content-Type": ["application/json"],
  "Accept": ["application/json"],
  "X-CustomHeader": ["some-value", "some-other-value"]
}

// Convert the request body to a JSON string
const serialized = request.body.text();
// Parse the string into a usable object
const body = JSON.parse(serialized);

Return an HTTPS Response

A custom endpoint Response object lets you configure the HTTPS response sent back to the caller. You can set the status code, customize headers, and include data in the response body.

response.setStatusCode(201);

response.setBody(
  "{'message': 'Hello, World!'}"
);

response.setHeader(
  "Content-Type",
  "application/json"
);

response.addHeader(
  "Cache-Control",
  "max-age=600"
);
response.addHeader(
  "Cache-Control",
  "min-fresh=60"
)

Example

Consider an endpoint function that parses the body of an incoming POST request, stores the parsed body in a MongoDB collection, and then responds to the caller:

exports = async function (request, response) {
   try {
      // 1. Parse data from the incoming request
      if(request.body === undefined) {
      throw new Error(`Request body was not defined.`)
      }
      const body = JSON.parse(request.body.text());
      // 2. Handle the request
      const { insertedId } = await context.services
      .get("mongodb-atlas")
      .db("myDb")
      .collection("myCollection")
      .insertOne({ date: new Date(), requestBody: body });
      // 3. Configure the response
      response.setStatusCode(201);
      // tip: You can also use EJSON.stringify instead of JSON.stringify.
      response.setBody(JSON.stringify({
         message: "Successfully saved the request body",
         insertedId,
      }));
   } catch (error) {
      response.setStatusCode(400);
      response.setBody(error.message);
   }
}

The function receives the following POST request:

curl -X POST \
   -H 'apiKey: abcde12345' \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \
   -d '{ "foo": "bar" }' \
   https://data.mongodb-api.com/app/myapp-abcde/endpoint/custom

{
  "message": "Successfully saved the request body",
  "insertedId": "639a521bbdec9b85ba94014b"
}

After the function verifies that the body of the incoming request is defined, it stores the parsed body as a new document in a collection named myCollection. The resulting output displays the configured response, which includes a custom message and the insertedId.

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 default data format specified in the endpoint configuration.

Authenticate the Request

If an endpoint is configured to use Application Authentication then you must include a valid user access token or login credentials with every request.

In general, bearer authentication with an access token has higher throughput and is more secure than credential headers. Use an access token instead of credential headers when possible. The token lets you run multiple requests without re-authenticating the user. It also lets you send requests from a web browser that enforces CORS.

To use an access token, first authenticate the user through an App Services authentication provider. Then, get the access token returned from App Services and include it in the request's Authorization header using a Bearer token scheme. For more information on how to acquire and use an access token, see Bearer Token Authentication.

curl -X GET \
   -H 'Authorization: Bearer <AccessToken>' \
   -H 'Content-Type: application/json' \
   https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello

Alternatively, you can include valid login credentials for the user in the request headers.

Authorize the Request

Depending on the endpoint configuration, your requests may need to include additional authorization information.