Variable Mapping

The Serverless API Gateway introduces a flexible and powerful way to manipulate API requests and responses dynamically through mapping configurations. This document outlines how the mapping functional

Overview

Variable mapping in the Serverless API Gateway allows for the transformation of request attributes before they reach the intended endpoint. This process involves modifying request headers and query parameters based on dynamic values derived from the request itself, JWT payload, configuration variables, or global variables. Such transformations are crucial for implementing custom logic, enriching requests with additional data, and ensuring seamless integration between different parts of your API ecosystem.

How Mapping Works

The mapping functionality is implemented through the mapping configs, which takes a request and variables and applies specified mappings to its headers and query parameters. This process consists of two main steps: resolving the dynamic values based on the mapping configuration and updating the request with these resolved values.

Resolving Dynamic Values

Dynamic values in the mapping configuration are specified with templates that reference different sources, such as request headers, JWT payload, configuration variables, or global variables. The resolveValue function parses these templates, extracts the required values from the appropriate sources, and returns the resolved values to be used in the request transformation.

Template Syntax

• $request.header.[headerName]: Retrieves a value from the request headers.

• $request.jwt.[claimName]: Retrieves a value from the decoded JWT payload.

• $config.[variableName]: Retrieves a value from the configuration variables defined in the API gateway config.

• $request.query.[parameterName]: Retrieves a value from the query parameters of the request.

Applying Mappings

Mappings can be applied to both request headers and query parameters:

• Headers Mapping: For each entry in the headers mapping configuration, the Serverless API Gateway function resolves the specified template to a value and sets this value in the request's headers.

• Query Parameters Mapping: Similar to headers, for each entry in the query mapping configuration, the Serverless API Gateway resolves the specified template to a value and adds or updates this value in the request's query parameters.

Configuration Example

The mapping configuration is part of the API gateway configuration file, under the paths section. Here is a simplified example showing how mappings can be configured:

"paths": [
    {
        "method": "GET",
        "path": "/api/v1/example",
        "integration": {
            "type": "http_proxy",
            "server": "serverlessapigateway-api"
        },
        "auth": true,
        "mapping": {
            "headers": {
                "x-custom-header": "$request.jwt.customClaim"
            },
            "query": {
                "user": "$request.query.userId"
            }
        },
        "variables": {
            "api_key": "API_KEY_VALUE"
        }
    }
]

In this example, a custom header x-custom-header is added to the request, with its value set to a custom claim from the JWT payload. Additionally, a query parameter user is set based on the userId query parameter in the original request.

Conclusion

The mapping functionality in the Serverless API Gateway offers a powerful mechanism for dynamically manipulating API requests. By utilizing templates to resolve values from various sources, developers can implement sophisticated logic to transform requests on the fly, ensuring that the API gateway can efficiently handle the diverse needs of modern web applications.