HTTPS Endpoints

Endpoint Routes

Every HTTPS endpoint has a unique route that serves as a name for the endpoint. You call an endpoint by appending its route to your app's base URL and sending an HTTP request. Route names must begin with a forward slash (/) and may contain additional forward slashes to indicate a nested path.

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

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/<Route>

HTTP Methods

You can configure an endpoint to accept only a specific HTTP method or allow any method and handle each type within the endpoint function.

HTTPS endpoints support the following standard HTTP methods:

• GET
• POST
• PUT
• PATCH
• DELETE

Endpoint Functions

Each request sent to an HTTPS endpoint calls an associated serverless function that handles the logic for the endpoint. The function runs your custom code and can import libraries from npm, connect to a linked MongoDB Atlas cluster, and call other serverless functions.

Endpoint functions receive arguments that describe the incoming request and allow you to modify the response sent back to callers.

exports = async function (request, response) {
  // ... your code here
}

exports = async function (request, response) {
  // 1. Parse the incoming request
  const bodyJson = JSON.parse(request.body.text());
  // 2. Run the endpoint logic
  await context.services
    .get("mongodb-atlas")
    .db("myDb")
    .collection("myCollection")
    .insertOne({ date: new Date(), requestBody: bodyJson });
  // 3. Configure the response
  response.setBody("Request was successful");
}

Request Objects

The first argument of an endpoint function is a request object that includes information about the incoming HTTP request that called the endpoint.

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

Response Objects

The second argument of an endpoint function is a response object that represents HTTPS response sent back to the caller. The object includes methods that you can call to configure the response.

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"
)

Return Type Override

When calling an endpoint, use the Accept header to control the response type:

System Authentication

If the endpoint function is configured to run as the system user, incoming requests do not need to include any user credentials or tokens. The endpoint will not enforce any Rules or validate your Schemas.

Application Authentication

If the endpoint function is configured to use application authentication, incoming requests must include one or more headers that contain valid user credentials. Users can authenticate with any of the following configured authentication providers:

• Email/Password

  curl -X GET \
     -H 'email: <Email Address>' \
     -H 'password: <Password>' \
     -H 'Content-Type: application/json' \
     https://data.mongodb-api.com/app/myapp-abcde/endpoint/test

• API Key

  curl -X GET \
     -H 'api-key: <API Key>' \
     -H 'Content-Type: application/json' \
     https://data.mongodb-api.com/app/myapp-abcde/endpoint/test

• Custom JWT

  curl -X GET \
     -H 'jwtTokenString: <Custom JSON Web Token>' \
     -H 'Content-Type: application/json' \
     https://data.mongodb-api.com/app/myapp-abcde/endpoint/test

Secret Query Parameter

The secret query parameter request validation option requires that incoming requests include the secret value as a query parameter appended to the end of the URL.

Every request must include the secret value as the secret query parameter:

<endpoint URL>?secret=12345

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{ "message": "HELLO" }' \
     https://data.mongodb-api.com/app/myapp-abcde/endpoint/testSecretQueryParam?secret=12345

Payload Signature Verification

Payload signature verification requires that incoming requests include an HTTP header where the value is a hexadecimal-encoded HMAC SHA-256 hash generated from the request body and the secret value.

You could use the following function to generate the payload signature:

// Generate an HMAC request signature
exports = function signEndpointRequest(
  secret, // the secret validation string e.g. 12345
  body, // the endpoint request body e.g. { "message": "MESSAGE" }
) {
  return utils.crypto.hmac(EJSON.stringify(body), secret, "sha256", "hex");
}

Every request must include a payload signature in the Endpoint-Signature header:

Endpoint-Signature::sha256=<hex encoded hash>

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Endpoint-Signature::sha256=828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862" \
  -d '{"message":"MESSAGE"}' \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/testPayloadSignatureVerification