Skip to content

Request Object

By default, every endpoint function will receive an instance of the RequestClient class (aka request) as the first argument of their function. This request has a lot of properties which will do common things automatically, but still allows the developer to override those operations if they deem necessary. Below is a list and examples of all the properties of the request:

Example

Don't like reading documentation? Then look at our examples which can run locally!

Request Properties

property type mutable description
method string no the http method of the request
resource string no the AWS resource being invoked
authorizer object no if using a customized authorizer, the authorizer object
headers object no the headers of the request
params object no combination of query string and path params in one object
queryParams object no query string parameters from the request
pathParams object no the path parameters of the request
route string no the requested route with placeholders of params
path string no the raw requested path with actual param values
json object no the body of the request, converted from json string in object
xml object no the body of the request, converted from xml string in object
graphql string no the body of the graphql request as a string
body any no the body of the request, converted to based on data type
raw any no the raw body of the request no conversion
context object yes mutable request context to assigned and pass around
event object no the full event originally coming from the lambda

request.method

1
2
3
4
console.log(request.method);

// example output:
'get'

request.resource

1
2
3
4
console.log(request.resource);

// example output:
'/{proxy+}'

request.authorizer

Tip

This is only useful if you are using an external authorizer with your lambda.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
console.log(request.authorizer);

// example output:
{
    apiKey: 'SOME KEY',
    userId: 'x-1-3-4',
    correlationId: 'abc12312',
    principalId: '9de3f415a97e410386dbef146e88744e',
    integrationLatency: 572
}

request.headers

1
2
3
4
5
6
7
console.log(request.headers);

// example output:
{
    'x-api-key': 'SOME-KEY',
    'content-type': 'application/json'
}

request.params

Info

This combines both path parameters and query string parameters, nested in one object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
console.log(request.params);

// example output:
{
    query: {
        name: 'me'
    },
    path: {
        id: 1
    }
}

request.queryParams

1
2
3
4
5
6
console.log(request.queryParams);

// example output:
{
     name: 'me'
}

request.pathParams

1
2
3
4
5
6
console.log(request.pathParams);

// example output:
{
     id: 1
}

request.route

Info

This will provide the route with the path param variables included

1
2
3
4
console.log(request.route);

// example output:
'grower/{id}'

request.path

Info

This will provide the route with the path param values replacing the variables

1
2
3
4
console.log(request.path);

// example output:
'grower/1'

request.json

Warning

This will raise an unhandled exception if the body is not json compatible

1
2
3
4
5
6
console.log(request.json);

// example output:
{
    someJsonKey: 'someJsonValue'
}

request.xml

Warning

This will raise an unhandled exception if the body is not xml compatible

1
2
3
4
5
6
console.log(request.xml);

// example output:
{
    someXMLKey: 'someXMLValue'
}

request.graphql

Info

This is graphql string since there is no object equivalent; you can pass this directly to your graphql resolver

1
2
3
4
5
6
7
8
console.log(request.graphql);

// example output:
'{
    players {
        name
    }
}'

request.body

Tip

This is the safest way to get the body of the request. It will use the content-type header to determine the data sent and convert it; if the data can't be converted for whatever reason it will catch the error and return the raw body provided unconverted.

1
2
3
4
5
6
console.log(request.body);

// example output:
{
    someXMLKey: 'someXMLValue'
}

request.raw

1
2
3
console.log(request.raw);

// example output: whatever the raw data of the body is; string, json string, xml, binary, etc

request.context

Tip

This is the only mutable property of the request, to be used by any of the before or beforeAll middleware options

1
2
3
4
5
6
7
request.context = {application_assignable: true}
console.log(request.context);

// example output:
{
    application_assignable: true
}

request.event

Warning

This is the original full request. Not advisable to use this as defeats the purpose of the entire Acai. In addition, you don't want to mutate this object and potentially mess up the entire router.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
import { APIGatewayProxyEventV2 } from 'aws-lambda';

console.log(request.event);

// example output:
{
    "version": "2.0",
    "routeKey": "$default",
    "rawPath": "/my/path",
    "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
    "cookies": [
        "cookie1",
        "cookie2"
    ],
    "headers": {
        "header1": "value1",
        "header2": "value1,value2"
    },
    "queryStringParameters": {
        "parameter1": "value1,value2",
        "parameter2": "value"
    },
    "requestContext": {
        "accountId": "123456789012",
        "apiId": "api-id",
        "authentication": {
            "clientCert": {
                "clientCertPem": "CERT_CONTENT",
                "subjectDN": "www.example.com",
                "issuerDN": "Example issuer",
                "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
                "validity": {
                    "notBefore": "May 28 12:30:02 2019 GMT",
                    "notAfter": "Aug  5 09:36:04 2021 GMT"
                }
            }
        },
        "authorizer": {
            "jwt": {
                "claims": {
                    "claim1": "value1",
                    "claim2": "value2"
                },
                "scopes": [
                    "scope1",
                    "scope2"
                ]
            }
        },
        "domainName": "id.execute-api.us-east-1.amazonaws.com",
        "domainPrefix": "id",
        "http": {
            "method": "POST",
            "path": "/my/path",
            "protocol": "HTTP/1.1",
            "sourceIp": "IP",
            "userAgent": "agent"
        },
        "requestId": "id",
        "routeKey": "$default",
        "stage": "$default",
        "time": "12/Mar/2020:19:03:58 +0000",
        "timeEpoch": 1583348638390
    },
    "body": "Hello from Lambda",
    "pathParameters": {
        "parameter1": "value1"
    },
    "isBase64Encoded": false,
    "stageVariables": {
        "stageVariable1": "value1",
        "stageVariable2": "value2"
    }
}