Module: LambdaSharp.App.Api
Version: 0.8.3.5
Overview
The LambdaSharp.App.Api module is used by the App
declaration to create an API Gateway REST API proxy for CloudWatch Logs, Metrics, and Events that is used by the app. The API can be configured to limit access using the CoreOrigin
parameter. Access to the API is secured by an API key that is computed from the CloudFormation stack identifier and the app version identifier. Using the DevMode
parameter, the API can be configured for more lenient access and a simplified API key, which allows for accessing it from localhost.
Resource Types
This module defines no resource types.
Parameters
ParentModuleId
-
The
ParentModuleId
parameter specifies the module ID of the parent stack.Required: Yes
Type: String
ParentModuleInfo
-
The
ParentModuleInfo
parameter specifies the module information of the parent stack.Required: Yes
Type: String
LogGroupName
-
The
LogGroupName
parameter specifies the name of CloudWatch LogGroup for the app.Required: Yes
Type: String
RootPath
-
The
RootPath
parameter specifies the root path for app API. The root path must be a single path segment.Required: Yes
Type: String
Pattern:
^[a-zA-Z0-9._-]+$
CorsOrigin
-
The
CorsOrigin
parameter specifies the source URL that is allowed to invoke the API. The value must be http:// or https:// followed by a valid domain name in lowercase letters, or*
to allow any domain.Required: Yes
Type: String
Pattern:
^*|https?://((?!-)[a-z0-9-]{1,63}(?<!-).)+[a-z]{2,6}$
BurstLimit
-
The
BurstLimit
parameter specifies the maximum number of requests per second over a short period of time.Required: Yes
Type: Number
Value Constraints: Minimum value of 10.
RateLimit
-
The
RateLimit
parameter specifies the maximum number of requests per second over a long period of time.Required: Yes
Type: Number
Value Constraints: Minimum value of 10.
EventSource
-
The
EventSource
parameter specifies the 'Source' property override for app events. When empty, the 'Source' property is set by the app request.Required: Yes
Type: String
AppVersionId
-
The
AppVersionId
parameter specifies the app version identifier. This value is used to construct the complete API key.Required: Yes
Type: String
DevMode
-
The
DevMode
parameter specifies if the app API should run with relaxed API key constraints and enables debug logging. The value must be one ofEnabled
orDisabled
. Default value isDisabled
.Required: No
Type: String
The
DevMode
parameter must have one of the following values:Enabled
-
The API key is solely based on the CloudFormation stack identifer. Debug logging is enabled in the app.
Disabled
-
The API key is based on teh CloudFormation stack identifier and the app version identifier. Debug logging is disabled in the app.
Output Values
ApiKey
-
The
ApiKey
output contains the CloudFormation stack identifier portion of the API key.Type: String
Url
-
The
Url
output contains the URL of the api endpoint used by theLambdaSharpAppClient
.Type: String
DomainName
-
The
DomainName
output contains the domain name of the API Gateway instance.Type: String
CloudFrontOriginPath
-
The
CloudFrontOriginPath
output contains the origin path required by a CloudFront distribution to front the API.Type: String
CloudFrontPathPattern
-
The
CloudFrontPathPattern
output contains the path pattern required by a CloudFront distribution to front the API.Type: String
RootPath
-
The
RootPath
outputs contains the root path for the app API.Type: String
REST API
The REST API endpoint can be found in the Url
output value of the nested stack.
Authentication
The REST API expects a X-Api-Key
header in the request to validate access to the API.
The API key is computed by concatenating AppVersionId
with the colon character (i.e. ':'
) and the CloudFormation stack identifier, and then applying a base 64 encoding to the result. When DevMode
is enabled, the API key only uses the CloudFormation stack identifier.
To compute the effective API key, base 64 decode the ApiKey
output value and concatenate it to the app version identifier:
Headers["X-Api-Key"] = Base64Encode($AppVersionId + ':' + Base64Decode($ApiKey))
When DevMode
is enabled, the effective API key becomes:
Headers["X-Api-Key"] = $ApiKey
By default, the RootPath
parameter has value .app
, but this can be customized by the App
declaration.
POST:/${RootPath}/logs - Create Log Stream
Creates a new log stream in the app log group. A log stream is a sequence of log events that originate from an app instance.
There is no limit on the number of log streams that can be created. There is a limit of 50 requests-per-second on this operations, after which requests are throttled.
The log stream name must match the following guidelines:
- Log stream names must be unique within the log group.
- Log stream names can be between 1 and 512 characters long.
- The ':' (colon) and '*' (asterisk) characters are not allowed.
Request Syntax
{
"logStreamName": "string"
}
Request Parameters
The request accepts the following data in JSON format.
logStreamName
-
The name of the log stream.
Required: Yes
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[^:*]*
Success Response (HTTP Status Code: 200)
On success, the API responds with an empty JSON document.
{ }
Bad Request Response (HTTP Status Code: 400)
On a Bad Request response, the body contains a message describing why the request was rejected. Additional details can be found in the API logs when enabled.
Example: request body is missing required fields
{
"error": "Invalid request body"
}
Example: request validation error
{
"error": "1 validation error detected: Value \'\' at \'logStreamName\' failed to satisfy constraint: Member must have length greater than or equal to 1"
}
Internal Error Response (HTTP Status Code: 500)
On an Internal Error response, the body contains a generic message. The actual reason can be found in the API logs when enabled.
{
"error": "Unexpected response from service."
}
PUT:/${RootPath}/logs - Put Log Messages
Uploads a batch of log messages to the specified log stream.
The request must include the sequence token obtained from the response of the previous call, unless it is the first request to a newly created log stream. Using the same sequenceToken
twice within a narrow time period may cause both calls to be successful or one might be rejected.
The batch of events must satisfy the following constraints:
- The maximum batch size is 1,048,576 bytes. This size is calculated as the sum of all event messages in UTF-8, plus 26 bytes for each log event.
- None of the log events in the batch can be more than 2 hours in the future.
- None of the log events in the batch can be older than 14 days or older than the retention period of the log group.
- The log events in the batch must be in chronological order by their timestamp. The timestamp is the time the event occurred, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
- A batch of log events in a single request cannot span more than 24 hours. Otherwise, the operation fails.
- The maximum number of log events in a batch is 10,000.
- There is a quota of 5 requests per second per log stream. Additional requests are throttled. This quota cannot be changed.
Request Syntax
{
"logEvents": [
{
"message": "string",
"timestamp": number
}
],
"logStreamName": "string",
"sequenceToken": "string"
}
Request Parameters
The request accepts the following data in JSON format.
logEvents
-
The log events.
Required: Yes
Type: Array of log event objects
Array Members: Minimum number of 1 item. Maximum number of 10,000 items.
message
-
The raw event message.
Required: Yes
Type: String
Length Constraints: Minimum length of 1.
timestamp
-
The time the event occurred, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Required: Yes
Type: Long
Valid Range: Minimum value of 0.
logStreamName
-
The name of the log stream.
Required: Yes
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[^:*]*
sequenceToken
-
The sequence token obtained from the response of the previous call. An upload in a newly created log stream does not require a sequence token. Using the same
sequenceToken
twice within a narrow time period may cause both calls to be successful or one might be rejected.Type: String
Success Response (HTTP Status Code: 200)
On success, the API responds with a JSON document containing the sequence token for the next request.
{
"nextSequenceToken": "49608818592289528730168753288679022865213175397425034930"
}
Bad Request Response (HTTP Status Code: 400)
Example: request body is missing required fields
{
"error": "Invalid request body"
}
Example: request validation error
{
"error": "1 validation error detected: Value \'\' at \'logStreamName\' failed to satisfy constraint: Member must have length greater than or equal to 1"
}
Example: The sequenceToken
field is either missing or reusing a previous token value
{
"error": "The given batch of log events has already been accepted. The next batch can be sent with sequenceToken: 49608818592289528730168753288679022865213175397425034930",
"nextSequenceToken": "49608818592289528730168753288679022865213175397425034930"
}
Internal Error Response (HTTP Status Code: 500)
On an Internal Error response, the body contains a generic message. The actual reason can be found in the API logs when enabled.
{
"error": "Unexpected response from service."
}
POST:/${RootPath}/events - Send Events
Sends custom events to the default event bus in Amazon EventBridge so that they can be matched to rules.
Request Syntax
{
"Entries": [
{
"Detail": "string",
"DetailType": "string",
"Resources": [ "string" ],
"Source": "string"
}
]
}
Request Parameters
The request accepts the following data in JSON format.
Entries
-
The entry that defines an event in your system. You can specify several parameters for the entry such as the source and type of the event, resources associated with the event, and so on.
Required: Yes
Type: Array of event objects
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[^:*]*
Detail
-
A valid JSON string. There is no other schema imposed. The JSON string may contain fields and nested subobjects.
Required: Yes
Type: String
DetailType
-
Free-form string used to decide what fields to expect in the event detail.
Required: Yes
Type: String
Resources
-
AWS resources, identified by Amazon Resource Name (ARN), which the event primarily concerns. Any number, including zero, may be present.
Required: Yes
Type: Array of strings
Source
-
The source of the event.
Required: Yes
Type: String
Success Response (HTTP Status Code: 200)
On success, the events API responds with an empty JSON document.
{ }
Internal Error Response (HTTP Status Code: 500)
On an Internal Error response, the body contains a generic message. The actual reason can be found in the API Gateway logs when enabled.
{
"error": "Unexpected response from service."
}