Integrating ReadMe with Amazon API Gateway to Keep Your Developer Hub Up to Date

By Giedrius Praspaliauskas, Sr. Solutions Architect, Serverless – AWS

ReadMe

The modern API lifecycle does not end once your CI/CD pipeline pushes a deployment to production and the API becomes available to your clients. They still have to access documentation, try out different parts of the API, or get notifications about changes.

API developer portals have become standard for any business that is offering APIs to their partners and end users. Portals help your clients consume your APIs the way you designed them and get all of the necessary information, guidance, and initial support, along with help troubleshooting.

Amazon API Gateway publishes a regularly updated Serverless Developer Portal application in the AWS Serverless Application Repository and on GitHub.

There may be cases when this application is not enough, though. For example, when you need to integrate APIs across multiple vendor solutions or deployment targets, or when you need more complex API grouping into various products. In such cases, we recommend looking at our partner solutions that may fit your needs.

In this post, I will show you how to integrate one of the AWS Partner solutions, ReadMe.com, with Amazon API Gateway to make sure your documentation is up to date and gets changed every time you change the API.

Overview

This integration implementation reacts to changes to Amazon API Gateway made manually or through a CI/CD pipeline. It synchronizes changes from the API Gateway to the developer portal in ReadMe. It does this by exporting the API Gateway OpenAPI definition and uploading changes to ReadMe.

Optionally, it will delete the existing definition when you delete an API Gateway endpoint.

Figure 1 – Integration architecture.

Implementation uses the following resources:

• Amazon API Gateway that gets changed manually or by an automated process.
• Amazon EventBridge that receives change events whenever you deploy API Gateway stage.
• AWS Lambda function that’s invoked by EventBridge and synchronizes definition to ReadMe.
• AWS Systems Manager Parameter Store to store Lambda configuration parameters.
• AWS Secrets Manager to store ReadMe API key used for authentication.
• Amazon CloudWatch with alarms used for synchronization error notifications.
• Amazon Simple Notification Service (SNS) to deliver error notifications to the subscribed email recipients.

Prerequisites

You will need an existing ReadMe project which you’ll use as a synchronization target. If you do not have one yet, follow the instructions in the ReadMe documentation.

Note your project version and get an API key for authentication. If you plan to synchronize an API definition that already exists in your project, note that API definition ID as well. You will also need to have the API Gateway stage deployed. Note its ID, stage name, and API Gateway type (REST or HTTP).

Amazon CloudWatch metric alerts for Lambda errors will send notifications to an email address you provided at the deployment time. I recommend using an email alias; this way, you and your team will not miss notifications and leave issues unresolved.

Deploying Synchronization Application

The example in this post uses Python 3 and the AWS Serverless Application Model (AWS SAM) to deploy private APIs with custom domain names. Visit the documentation to install it in your environment.

To deploy the synchronization application AWS CloudFormation stack:

1. Clone the sample repository and navigate to the apigw-readme-integration directory.
   .
2. Run following commands to deploy the synchronization stack to the us-east-1 region:

python3 -m pip install -r requirements.txt
sam build 
sam deploy --guided --stack-name apigw-readme-sync –region us-east-1

3. Specify stack name, synchronization source, and destination parameters (API Gateway ID, stage name, type, ReadMe project version, existing API definition ID if known or “None”, API key, notification email) and accept default values for others.

Figure 2 – AWS SAM inputs.

4. You will receive an SNS subscription confirmation email to the address provided while configuring deployment. Click the subscription confirmation link to receive error alerts.
   .
5. Once the synchronization stack deployment completes, deploy the API Gateway stage specified as a source, wait a few minutes, and verify the application created new or changed existing API definition in the ReadMe project.

Figure 3 – ReadMe project example.

Implementation Walkthrough

Following are steps the application stack executes every time the API Gateway stage gets changed:

1. EventBridge receives the change event.
2. EventBridge will invoke the Lambda function if the event source, event name, API Gateway ID and stage specified in the event match one of the EventBridge rules created by the stack, and if the event does not contain error code.
3. If it’s the first time the Lambda function environment is starting, it will:
   1. Get configuration parameters from the Systems Manager Parameter Store (API Gateway ID, stage name, API Gateway type, ReadMe project version, API definition ID).
   2. Get ReadMe API Key from AWS Secrets Manager.
4. The Lambda function will:
   1. Export API Gateway definition as OpenAPI 3.0.1.
   2. Override API version in the metadata to match the ReadMe project.
   3. If API definition ID is specified in the parameters, update the API definition in ReadMe. If ID does not exist yet, you can upload the definition as a new one, note ID in the response, and update Systems Manager Parameter Store with the new value.
   4. In case of error while uploading to the ReadMe, log response status and rise error so that CloudWatch updates error metric, raises an alert, and SNS sends a notification.

Additional Notes

The EventBridge rules will also trigger the same Lambda function in case of the DeleteRestApi, DeleteApi, and DeleteStage events. I commented out in Lambda a call to the code that deletes API definition in ReadMe to avoid mistakes, as APIs do not get deleted that often. Enable it if desired; otherwise delete APIs in ReadMe manually.

Keep in mind you should delete your synchronization stack in CloudFormation after it deletes the API definition, or re-deploy with a new configuration.

Create a custom domain name in the API Gateway to make sure that API base URL in the developer portal does not show up as a default (https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/). Developer portal will use API Gateway custom domain name and base path mappings in the exported definition.

After initial synchronization of a new API, it updated ReadMe API definition ID in the Parameter Store. To avoid API definition duplication in the project, update your stack configuration as well if you re-deploy it.

For up-to-date implementation notes, please check the sample repository.

Limitations

API Gateway HTTP APIs use automated deployments that don’t send events and do not trigger this synchronization process. In case you use API Gateway HTTP API type with this synchronization approach, you will need to switch off automated deployment for the stage you are synchronizing, and start your API stage deployment as a part of your CI/CD pipeline.

Next Steps and Potential Modifications

Current deployment approach assumes a single CloudFormation stack per ReadMe project version and API definition combination. You may change and extend this implementation if you plan to manage large numbers of the versions and API definitions.

You could make it multi-API by storing multiple synchronization source/destination profiles in the Systems Manager Parameter Store. Then, make EventBridge rules less specific to invoke synchronization Lambda function for any API and any modification event. Function code will have to decide if this particular API is being tracked and needs to trigger the synchronization process, or just ignore it.

This way, a single Lambda function will react to multiple APIs being changed instead of a separate Lambda function deployment per API. As a result, you’ll have a single CloudFormation stack for all your API synchronization tasks.

Keep in mind that operational cost may increase. The Lambda function will execute for all API changes, even if some APIs are not part of the ReadMe projects.

Cleaning Up

To avoid incurring further charges when you do not need this synchronization process anymore, run the following command:

sam delete --stack-name apigw-readme-sync \
--region us-east-1

Conclusion

This post walks through implementing an API definition synchronization implementation between Amazon API Gateway and a ReadMe project. This approach allows developers and operators to keep their API documentation up to date and reflect the latest changes in the API Gateway deployments.

.

.

ReadMe – AWS Partner Spotlight

ReadMe is an AWS Partner that transforms your API docs into interactive hubs that help developers succeed.

Contact ReadMe | Partner Overview