How do you maintain your RESTful API design using Git, GitHub, and API Gateway?

One thing I’ve found helpful when using Git for RESTful API design is to leverage the power of Git tags. Tagging specific commits allows you to mark certain milestones or versions of your API, if you ever need to reference or revert to a specific version of your API design, you can easily do so using the associated tag. I disagree with the notion that Git alone is sufficient for maintaining a RESTful API design. While Git is instrumental in version control, it's equally important to have a robust review process in place. Platforms like GitHub provide features such as pull requests, which allow team members to review, comment on, and suggest changes to the API design before it's merged into the main branch.

Keeping the README file updated with APIs works for small services like microservices, but if we work on a monolith project the preferable way is to use Swagger or similar services to manage the API Docs and include the links inside the README.

One thing I’ve found helpful when using GitHub for RESTful API design is the use of GitHub Actions. These are automated workflows that can be triggered by various GitHub events, such as push or pull requests and I disagree with the idea that just generating a web page from API specification files is enough for comprehensive documentation.

One helpful thing I’ve found when using API Gateway is the ability to set up custom domain names for different stages of the API. This not only provides a more professional appearance but also makes it easier for consumers to remember and access the API endpoints.

An example I’ve seen of the innovative use of API Gateway is when organizations integrate it with serverless architectures like AWS Lambda. This allows them to execute backend code in response to API calls without provisioning or managing servers. The combination of API Gateway with serverless functions can lead to highly scalable, efficient, and cost-effective solutions.

Here is an example of how we could use Git, GitHub, and API Gateway to maintain your RESTful API design: - You start by creating a new repository on GitHub for your API project. - You add your API specification files (such as OpenAPI or RAML) to the repository. - You start working on a new feature for your API. - You create a new branch for the feature and start making changes to your API specification files. Once you are happy with the changes you have made, you commit and push your changes to the branch. - You open a pull request to merge the changes from your branch into the main branch. Another developer reviews your changes and merges them into the main branch. You deploy the latest version of your API to API Gateway.