HTTP Endpoint Configuration Files

Atlas App Services has reached its end-of-life status and is no longer actively supported by MongoDB. Triggers remain available in the Atlas UI. Refer to the deprecation page for details.

Note

This page describes a legacy configuration file format. You should only use this information if you're using the deprecated realm-cli.

Any configuration files you pull with App Services CLI or export from the UI use the latest configuration version. For detailed information on the current configuration file format, see App Configuration.

app/
└── http_endpoints/
    ├── config.json
    ├── data_api_config.json
    └── <Service Name>/
        ├── config.json
        ├── rules/
        │   └── <Rule Name>.json
        └── incoming_webhooks/
            └── <Webhook Name>/
                ├── config.json
                └── source.js

Custom HTTPS Endpoint Configuration

Define the configurations for your all of your app's custom HTTPS endpoints as an array in http_endpoints/config.json.

[
  {
    "route": "<Endpoint route name>",
    "http_method": "<HTTP method>",
    "function_name": "<Endpoint function name",
    "validation_method": "<Authorization scheme>",
    "secret_name": "<Validation Secret Name>",
    "respond_result": <boolean>,
    "fetch_custom_user_data": <boolean>,
    "create_user_on_auth": <boolean>,
    "disabled": <boolean>
  }
]

Field	Description
`route` string	The endpoint route.
`http_method` string	The type of HTTP method that the endpoint handles. Specify `` to handle all methods with a single endpoint. One of: `"GET"` `"POST"` `"PUT"` `"PATCH"` `"DELETE"` `"DELETE"` `""`
`function_name` string	The name of the function associated with the endpoint. The function should use the endpoint function signature.
`validation_method` string	The endpoint authorization scheme used to validate incoming requests. One of: `"SECRET_AS_QUERY_PARAM"` `"VERIFY_PAYLOAD"` `"NO_VALIDATION"`
`secret_name` string	The name of a secret that contains a string. If `validation_method` is set to `SECRET_AS_QUERY_PARAM` or `VERIFY_PAYLOAD`, this secret is used to authorize requests.
`respond_result` boolean	If `true`, the endpoint returns a customizable HTTP response to the client. You configure the response by calling the methods on the Response object. If you do not configure the response, the endpoint returns a `200 - Ok` response with the value returned from the endpont function as the request body. If `false`, requests return a `204 - No Content` response with no data in the body.
`fetch_custom_user_data` boolean	If `true`, the authenticated user's custom user data document is available via `context.user.custom_data`. If `false`, the user's custom data is not queried and `context.user.custom_data` is an empty object.
`create_user_on_auth` boolean	If `true`, your app automatically creates a new user if the provided user credentials authenticate successfully but aren't associated with an existing user. This setting is useful for apps that integrate with external authentication system through the Custom JWT authentication provider. If a request includes a valid JWT from the external system that doesn't correspond to a registered user, this creates a new user with the JWT as an identity.
`disabled` boolean	Enables (`false`) or disables (`true`) the endpoint.

Data API Configuration

Define the configuration for your app's generated Data API endpoints in http_endpoints/data_api_config.json.

{
  "disabled": <boolean>,
  "versions": ["v1"],
  "return_type": "EJSON" | "JSON",
  "create_user_on_auth": <boolean>,
  "run_as_system": <boolean>,
  "run_as_user_id": "<User Account ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

Field	Description
`disabled` boolean	If `false`, the Data API is not enabled. Generated endpoints will not handle or respond to requests.
`versions` string[]	An list of Data API versions that your app supports. The list may include a subset of all possible versions but must list the versions in ascending order. You cannot enable a version other than the most recent version but any previously enabled versions listed here will continue to work. Available Versions: `"v1"`
`return_type` string	The data format to use for data returned by endpoints in HTTPS response bodies. One of: `"EJSON"` `"JSON"`
`create_user_on_auth` boolean	If `true`, your app automatically creates a new user if the provided user credentials authenticate successfully but aren't associated with an existing user. This setting is useful for apps that integrate with external authentication system through the Custom JWT authentication provider. If a request includes a valid JWT from the external system that doesn't correspond to a registered user, this creates a new user with the JWT as an identity.
`run_as_user_id` string	An application user's account ID. If defined, endpoints will always run as the specified user. Cannot be used with `run_as_user_id_script_source`.
`run_as_user_id_script_source` string	Stringified source code for a function that returns an application user's account ID. If defined, endpoints execute the function on every request and run as the user with the ID returned from the function. Cannot be used with `run_as_user_id`.

HTTP Service Configuration

Deprecated legacy HTTP services are grouped into named services within /http_endpoints.

http_endpoints/<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "http",
  "config": {}
}

Field	Description
`name` String	The name of the HTTP endpoints service. This must be unique among all HTTP endpoint services in the app and match the name of its containing directory.
`type` String	For HTTP endpoints, this value is always `"http"`.
`config` String	Additional configuration options for the service. HTTP Endpoints currently have no additional configuration options.

Service Action Rules

You define service action rules in the service's rules/ sub-directory. Each rule maps to its own .json configuration file with the same name as the rule.

http_endpoints/<Service Name>/rules/<Rule Name>.json

{
  "name": "<Rule Name>",
  "actions": ["<Service Action Name>"],
  "when": { <JSON Rule Expression> }
}

Field	Description
`name` String	The name of the service rule. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens.
`actions` Array<String>	A list of HTTP actions that the rule applies to.
`when` Document	A rule expression that evaluates to `true` when the rule applies to a given request.

Incoming Webhooks

Configuration

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/config.json

{
  "name": "<Webhook Name>",
  "can_evaluate": { <JSON Expression> },
  "run_as_authed_user": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>",
  "fetch_custom_user_data": <Boolean>,
  "create_user_on_auth": <Boolean>,
  "respond_result": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

Field

Description

name

String

The name of the webhook. This must be unique among all webhooks in the HTTP endpoints service and match the name of its containing directory.

can_evaluate

JSON Expression (default: true)

A JSON expression that evaluates to true if the webhook is allowed to execute. Atlas App Services evaluates this expression for every incoming request.

disable_arg_logs

Boolean

If true, App Services omits the arguments provided to the webhook from the function execution log entry.

run_as_authed_user

Boolean

If true, the webhook function runs in the context of an existing application user specified by each incoming request. Incoming requests must include the user's authentication provider credentials in either the request body or the request headers.

Tip

For an example of how to specify credentials, see Configure Service Webhooks.

run_as_user_id

String

The unique ID of a App Services User that the function always executes as. Cannot be used with run_as_user_id_script_source or run_as_authed_user.

run_as_user_id_script_source

String

A stringified function that runs whenever the webhook is called and returns the unique ID of a App Services User that the function executes as. Cannot be used with run_as_user_id or run_as_authed_user.

respond_result

Boolean

If true, App Services includes the webhook function return value as the body of the HTTP response it sends to the client that initiated the webhook request.

fetch_custom_user_data

Boolean

If true, App Services queries the requesting user's custom user data and, if it exists, exposes the data as an object on the context.user.custom_data property.

This option is only available if run_as_authed_user is set to true.

create_user_on_auth

Boolean

If true, App Services automatically creates a new user based on the provided user credentials if they don't match an already existing user (e.g. no other user has the specified email address). The authentication provider that corresponds to the credentials must be enabled at the time of the request to create a new user.

This option is only available if run_as_authed_user is set to true.

options

Document

A document that contains configuration options for the webhook.

{
  "httpMethod": "<HTTP Method>",
  "validationMethod": "<Webhook Validation Method>",
  "secret": "<Webhook Secret>"
}

Field	Description
`httpMethod` String	The HTTP method type that the webhook accepts. Incoming webhook requests must use this method.
`validationMethod` String	The name of the request validation method that the webhook uses. Valid options: `"VERIFY_PAYLOAD"` `"SECRET_AS_QUERY_PARAM"` `"NO_VALIDATION"`
`secret` String	The secret value used to validate incoming webhook requests.

Source Code

You define a webhook function's source code in a source.js file within the webhook directory. Each file must export the main function that runs whenever a request calls the webhook.

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/source.js

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

What are the Atlas Application Services?