API Configuration

Default Required Environment Variables

To successfully deploy an Atlas-based application to AWS, you must define the following environment variables in the environment where the deployment process will be executed:

AWS_ACCESS_KEY_ID: AWS account/profile access key credential.
AWS_SECRET_ACCESS_KEY: AWS account/profile secret access key credential.
AWS_DEFAULT_REGION: Region of the AWS account where the deployment will be carried out.
APP_NAME: The application name in Pascal case, e.g. "MyApp". Used to generate resource names consistently across the infrastructure.

If in a local environment, the declaration of these and other environment variables can be conveniently done through the .atlas/.env.local file, as suggested in the Atlas API Template's README.

Domain Configuration

Although optional, it’s very common for applications to be accessible through a custom domain.

If that’s the case, the domain must be linked to a Route 53 hosted zone, and the following environment variables must be defined:

AWS_DOMAIN_NAME: The domain name used as the application's CloudFront alias. Not required if domainlessly deploying.
AWS_HOSTED_ZONE_ID: The Route 53 hosted zone ID associated with the registered domain specified above. Not required if domainlessly deploying.

Database Configuration

This section is also optional, but in most cases, your API will have its own PostgreSQL database where all the models' data will be created and stored.

If that applies, make sure to define the following environment variables and ensure that the .atlas/api-config.json file does not contain the declaration "databaseless": true.

DB_HOST: Database hostname.
DB_PORT: Database port.
DB_NAME: Database name.
DB_USER: Database user.
DB_PASSWORD: Database password.

Default Misc. Environment Variables

These environment variables are also optional but declaring values for them may be useful for localization and database migration behavior purposes.

APPLY_MIGRATION_IMMEDIATELY: Configures if any database migration detected should be automatically applied when deployment is finished. Not recommended for production deployment. If omitted, it defaults to false.
LANGUAGE: API's language used for error messages through the Messages class. If omitted, the default language used will be en.

Infrastructure: API-level Configuration Options

You can customize your Atlas-based API's infrastructure through multiple available options, all declarable in .atlas/api-config.json. These settings apply globally across the API or affect multiple endpoints at once.

Note that all mentions to HTTPMETHOD references the endpoint's HTTP method (e.g. "GET.py", "POST.py", "PATCH.json", etc.), used for naming Lambda handler and endpoint-level configuration files.

Below are described each option's usage and its impact on the API.

enabled_endpoints

Array that defines which standalone endpoints will be included in the API build. Each endpoint must be configured by following the JSON structure shown below:

route: Relative path to the HTTPMETHOD.py handler file(s) located within a directory under src/functions whose path matches this pattern, e.g. "src/functions/hello-world". Supports globbing syntax: * for single next segment, ** for any number of next segments.
http_method_whitelist: Optional. Restricts which HTTPMETHOD.py files will be included for this route. By default, all HTTPMETHOD.py handlers will be read.

Example:

.atlas/api-config.json

{
    "enabled_endpoints": [
        {
            "route": "/hello-world",
            "http_method_whitelist": ["GET"]
        },
        {
            "route": "/categories/*/options",
            "http_method_whitelist": ["GET", "DELETE"]
        },
        {
            # This will not include the "/manager/products" route
            "route": "/manager/products/**",
        },
        {
            # This will include the "/manager/categories" route
            "route": "/manager/categories**",
        }
    ]
}

enabled_endpoint_groups

Array that defines groups of endpoints that will be included in the API build. Each endpoint group must be configured by following the JSON structure shown below:

name: Name of the endpoint group.
is_public: Makes the group's endpoints publicly accessible. If omitted, it defaults to false.
endpoints: List of endpoints contained in the group.

Example:

.atlas/api-config.json

{
    "enabled_endpoint_groups": [
        {
            "name": "ManagerProducts",
            "endpoints": [
                { "route": "/manager/products**" },
                { "route": "/manager/prices**" },
                { "route": "/manager/stocks**" }
            ]
        },
        {
            "name": "ManagerCategories",
            "endpoints": [
                { "route": "/manager/categories**" }
            ]
        }
    ]
}

env_vars

Array containing the API's environment variables, conveniently accessible inside endpoints through the Environment class. These values will be stored in a secret in AWS Secrets Manager.

The following environment variables' values are captured in deployment environment and included by default:

APP_NAME
__APP_NAME_KEBAB_CASE__ (autogenerated from APP_NAME, don't declare it)
DB_HOST
DB_PORT
DB_NAME
DB_USER
DB_PASSWORD
APPLY_MIGRATION_IMMEDIATELY
LANGUAGE

Example:

.atlas/api-config.json

{
    "env_vars": [
        "AUTH_TOKEN_TTL",
        "SES_FROM_NAME",
        "SES_FROM_EMAIL_DOMAIN",
        "SES_FROM_EMAIL_ADDRESS"
    ]
}

databaseless

Boolean value that, if set as true, will enable deployment without specifying database credentials (DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD). If omitted, it defaults to false.

Example:

.atlas/api-config.json

{
    "databaseless": true
}

tracing

Boolean value that, if set as true, will enable tracing via AWS X-Ray for all endpoints. If omitted, it defaults to false.

Example:

.atlas/api-config.json

{
    "tracing": true
}

is_public

Boolean value that, if set as true, will make all endpoints publicly accessible. If omitted, it defaults to false.

Example:

.atlas/api-config.json

{
    "is_public": true
}

enable_auth

Boolean value that, if set as true, enables Atlas’ API Gateway Authorizer and the auth_tokens DynamoDB table for managing bearer authorization tokens and fine-grained access control. If omitted, defaults to false. Only endpoints with "is_public": true will be accessible if this flag is set to false.

Example:

.atlas/api-config.json

{
    "enable_auth": true
}

timeout

Numeric value that defines the execution timeout (in seconds) for all endpoints. If omitted, defaults to 10.

Example:

.atlas/api-config.json

{
    "timeout": 15
}

memory_size

Numeric value that sets the memory allocation (in MB) for all endpoints. Increasing this value also proportionally increases available CPU power. If omitted, defaults to 128.

Example:

.atlas/api-config.json

{
  "memory_size": 256
}

snap_start

Boolean flag that, if set as true, enables Lambda SnapStart for faster cold starts on all endpoints. If omitted, defaults to false.

Example:

.atlas/api-config.json

{
  "snap_start": true
}

throttle_rate

Numeric value that defines the steady-state request rate limit (requests per second) applied to the API Gateway's Usage Plan (linked to the API Gateway's general API key injected by CloudFront as reverse-proxy). Requests beyond this rate may be throttled. If omitted, defaults to 10.

Example:

.atlas/api-config.json

{
  "throttle_rate": 100
}

throttle_burst

Numeric value that sets the maximum burst capacity of requests allowed before throttling begins (token bucket limit). Works together with throttle_rate. If omitted, defaults to 20.

Example:

.atlas/api-config.json

{
  "throttle_burst": 200
}

max_requests_per_day

Numeric value that limits the total number of requests per day for the API. Once reached, further requests are blocked until the next 24-hour window. If omitted, defaults to 1000.

Example:

.atlas/api-config.json

{
  "max_requests_per_day": 20000
}

max_request_payload_size

Numeric value that defines the maximum payload size (in bytes) allowed per request. Requests exceeding this limit are rejected with an error. If omitted, defaults to 1000000 (1MB).

Example:

.atlas/api-config.json

{
  "max_request_payload_size": 1048576
}

Infrastructure: Endpoint-level Configuration Options

Endpoint-level configuration options are unique, private infrastructure settings for individual endpoints.

These settings are defined within each endpoint’s __config__/HTTPMETHOD.json file and take precedence over broader configuration layers such as groups or the global .atlas/api-config.json.

Note that all mentions to HTTPMETHOD references the endpoint's HTTP method (e.g. "GET.py", "POST.py", "PATCH.json", etc.), used for naming Lambda handler and endpoint-level configuration files.

Below are described each option's usage and its impact on the endpoint.

is_public

Boolean value that, if set as true, will make the endpoint publicly accessible. If omitted, it defaults to false.

Example: