Priority Variables

Variable resolution priority in Serverless API Gateway mappings. Local config variables override global variables per endpoint.

Variable Resolution Hierarchy

The Serverless API Gateway uses a specific order of precedence when resolving variables to ensure that the most relevant and specific settings are applied to each request. This order is as follows:

Local (Config) Variables: These are variables defined within the scope of a specific path in the API gateway configuration. They are intended to be specific to the individual endpoint or set of endpoints defined by that path configuration. When a variable is referenced in a mapping, the system first checks if it exists as a local variable for that path.
Global Variables: Global variables are defined at a higher level in the API gateway configuration and are intended to provide default values that apply across multiple paths or the entire API. If a variable referenced in a mapping is not found among the local variables, the system then checks the global variables for a match.

Why Local Variables Take Precedence

The prioritization of local variables over global ones is designed to provide flexibility and specificity in API configuration. This approach allows developers to:

Override Global Settings: Define specific behaviors or values for certain endpoints without changing the global configuration. This is useful for exceptions or special cases within your API.
Maintain Configurational Flexibility: Easily adjust the behavior of individual endpoints or groups of endpoints without affecting the entire API, making it easier to test changes or roll out endpoint-specific features.
Enhance Configuration Clarity: Keep configurations clear and understandable by allowing endpoint-specific variables to be defined close to where they are used, improving maintainability and readability.

Example

Consider an API configuration where a global variable database-url is defined to point to a primary database. However, for a specific endpoint, you want to route requests to a different, endpoint-specific database. By defining a local variable database-url within the path configuration for that endpoint, the API gateway will use this local variable in preference to the global one for requests to that endpoint, ensuring that requests are routed to the correct database.

"variables": {
    "global_variable": "global_value",
    "database-url": "sqlite://primary-db.sqlite" // Global variable
},
"paths": [
    {
        "method": "GET",
        "path": "/api/v1/special-endpoint",
        "variables": {
            "database-url": "sqlite://special-db.sqlite" // Local variable takes precedence
        }
    }
]

In this setup, requests to /api/v1/special-endpoint will use sqlite://special-db.sqlite for the database-url, overriding the global setting of sqlite://primary-db.sqlite.

Conclusion

The prioritization of local variables over global variables in the Serverless API Gateway's mapping functionality provides a powerful tool for fine-tuning API behavior. It allows developers to create more specific, flexible, and maintainable API configurations, ensuring that each part of the API behaves exactly as needed without unnecessary global changes.