Module: LambdaSharp.App.Api

Version: 0.8.2.4

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 of Enabled or Disabled. Default value is Disabled.

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 the LambdaSharpAppClient.

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."
}