These private API examples, using Amazon API Gateway REST APIs, utilizes private API, and private integration. These samples 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 patterns here will benefit beginners as well as seasoned developers looking to improve their applications by automating routine tasks.
Examples are based on the fargate-rest-api. For private APIs the following additional considerations are implemented, compare to their regional counterparts:
- VPC interface endpoints are required in the application VPC to invoke the private API
- AWS CodeBuild for unit and integration testing needs to be associated with the VPC and security group to invoke the private API
- Resource policy is needed for the private API
- Resource policy behavior when used with Lambda authorizer Policy Evaluation Outcome
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
-
Every new client is first required to use their credentials to authenticate with Amazon Cognito and retrieve an identity token.
-
The API uses Amazon API Gateway as a front door. Client must then pass the identity token as a bearer token in the Authorization header with each subsequent request. When the API is configured as private, the public networks are not made available to route to your API. Private API endpoint can only be accessed from your VPC by using an interface VPC endpoint that you have configured. In addition, you must have a resource policy attached to your private API for it to be accessed.
-
The Lambda Authorizer inspects this token and generates an IAM policy that is returned back to API Gateway. It's important to keep in mind, when Lambda Authorizer and resource policy are used together, they are evaluated together. If the Lambda Authorizer generated IAM policy neither allows nor denies, along with API Gateway resource policy allow, the call will be allowed. For non-private, regional APIs, without any resource policy, same call will be denied. That is why API Gateway resource policy uses explicit deny for this sample.
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.
-
This API utilizes private integration for the backend, using AWS PrivateLink. AWS PrivateLink allows access to AWS services, while maintaining network traffic within the AWS network. After authentication and authorization is complete, API Gateway forwards requests to Network Load Balancers (through the Private Link) which distribute the requests to the ECS tasks, where the business logic resides. Data is persisted in DynamoDB tables, one table per API resource.
The container images for the ECS tasks are stored in Amazon ECR private repositories. This example also demonstartes, how to containerize your application using Dockerfile and CICD process.
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.
Each example is deployed via a CI/CD pipeline. As part of the pipeline, a code repository will be created to store the application code, as well as two environments - staging and production. Each of the environments will have all necessary resources including their own shared VPC and 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 create the CI/CD pipeline.
Check these implementations of the example API for more details and resources to explore.
- javascript-private-nlb-ecs-sam - this private REST API implementation uses Node.js on Amazon ECS, AWS Fargate, Amazon API Gateway, Network Load Balancer, AWS SAM, AWS CloudFormation