# Variable Mapping

### 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:

```json
"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.