These REST API examples demonstrate end-to-end implementations of a simple application using a serverless approach that includes CI/CD pipelines, automated unit and integration testing, and workload observability. The examples include multiple implementations of the same application using a variety of development platform and infrastructure as a code approaches. The patterns here will benefit beginners as well as seasoned developers looking to improve their applications by automating routine tasks.
There are various blog posts and code examples for serverless APIs available, however, most of them do not go beyond the first steps of implementing business logic and access controls. These example dive deeper including:
- CI/CD pipelines containing automated unit and integration testing
- manual approval steps before updates go live
- automated alerts and dashboards for workload observability.
- API access logging as part of SAM templates
- business specific metrics
Examples are (loosely) based on a SpaceFinder project. The services used by this application include Amazon API Gateway, Amazon Cognito, AWS Lambda, and Amazon DynamoDB. The CI/CD pipelines use AWS CodePipeline, AWS CodeCommit, and AWS CodeBuild.
The API uses Amazon API Gateway as a front door. Every new client is first required to use their credentials to authenticate with Amazon Cognito and retrieve an identity token. They must then pass this as a bearer token in the Authorization header with each subsequent request. The Lambda Authorizer inspects this token and generates an IAM policy that is returned back to API Gateway.
The content of the IAM policy generated by the Lambda Authorizer depends on the user role and identity. All users have read access to the Locations and Resources associated with Locations. They also have read/write access their own Bookings. Administrative users have read/write access to all Locations, Resources, and Bookings. User status (regular vs. administrative) is defined by their membership in the API administrators group in Amazon Cognito User Pool.
After authentication and authorization is complete, API Gateway forwards requests to AWS Lambda functions to implement application business logic. Data is persisted in DynamoDB tables, one table per API resource.
These examples create following resources in your AWS account:
- API Gateway endpoint that serves all API requests
- Lambda function used as a Lambda Authorizer for API Gateway
- Lambda functions to process requests coming to API Gateway
- DynamoDB tables to store data
- IAM Roles and permissions for Lambda functions
- API Gateway access logs stream in CloudWatch Logs
- SNS topic for the alarms
- API Gateway HTTP errors alarm
- Errors alarms for all Lambda functions
- Throttling alarms for all Lambda functions
- Throttling alarms for all DynamoDB tables
- CloudWatch Dashboard with API Gateway, Lambda, DynamoDB, and business metrics preconfigured
One of the easiest ways to see all those resources listed is navigating to the AWS Console, picking the Lambda service and checking out the Applications link on the left:
Each example implements logging using CloudWatch Logs, emits custom metrics using Embedded Metrics Format, configures CloudWatch alerts, and creates a CloudWatch dashboard. X-Ray distributed tracing is enabled whenever it is supported. Lambda functions bundle the X-Ray SDK for additional instrumentation. API Gateway access logging is enabled with a 30 day retention period. SAM templates override the default Lambda log stream to set the retention period to 7 days.
For better manageability and cost visibility examples use "Stack" tag whenever possible. You may need to activate them for use in AWS Cost Explorer, see documentation for more details.
Check the CloudFormation outputs of your deployment to see the CloudWatch dashboard URL, references to the API Gateway access logs stream, and alarms topic in SNS.
To receive alerts you will need to create a subscription for the SNS topic. See documentation for instructions.
The dashboards are operational immediately:
Each example includes unit and integration tests that are run automatically by the CI/CD pipeline. See the documentation of a particular example for the instructions on how to run tests manually.
Each example provides two ways to deploy resources - manual and CI/CD pipeline driven.
If you choose to deploy components manually you will need to deploy a shared Cognito stack. Don't forget to update parameter values in templates or code accordingly if you used a shared stack name different from the one used in documentation.
When you choose to use a CI/CD pipeline to deploy resources you will create a code repository and two environments - staging and production. Each of the environments will have all necessary resources including their own shared Cognito stacks. The build stage will automatically perform all unit tests. Staging will run integration tests before stopping for a manual production deployment approval step.
See individual example documentation for detailed instructions on how to deploy the example manually or create CI/CD pipeline.
Check these implementations of the example API for more details and resources to explore.
- python-rest-sam - this REST API implementation uses Python, AWS SAM, AWS CloudFormation
- javascript-http-sam - this HTTP API implementation uses Node.js, AWS SAM, AWS CloudFormation
- python-http-sam - this HTTP API implementation uses Python, AWS SAM, AWS CloudFormation
- python-http-cdk - this HTTP API implementation uses Python, AWS CDK, AWS CloudFormation
- shared - resources shared across the projects, such as Amazon Cognito stack, Amazon Virtual Private Cloud stack, etc.