I was profiling the banking API bunq over the weekend and noticed they were managing their Postman collections on GitHub. I have long been an advocate for API providers to manage OpenAPI and Swagger on GitHub, managing as they would any other piece of code or machine readable artifact. Anytime I find API providers like the New York Times, Box, and Slack, I make sure and try to write a post showcasing the practices, so other API providers will consider following their lead. Encouraging providers to not just manage their API definitions on GitHub, but also be very vocal about how and why you are doing it, so others will learn along the way.
If you notice, Slack manages their OpenAPI, as well as their AsyncAPI and JSON Schema within the same GitHub repository. I recommend that other API providers do this, providing a single API definitions repository, and managing the following API definitions within the repository:
- OpenAPI - Publishing API definitions for HTTP 1.1 APIs.
- AsyncAPI - Publish API definitions for HTTP 11.1, HTTP/2, and TCP APIs.
- JSON Schema - Publish the schema for all objects to GitHub.
- Postman Collections - Publish reference and workflow Postman collections.
- Postman Environments - Publish the Postman environments.
- ALPS Profiles - Publish your ALPS profiles to your GitHub repository.
If there are other API definition formats you use, publish them all to the same repository. Then wrap them all in a single APIs.json index, providing a manifest for the machine and human readable elements of your API operations. bunq provides Postman collection for their banking API, and they also provide two separate environment definitions, one for the PSD2 compliant sandbox environment, and the other for the PSD2 compliant production environment. Managing the reference definition for the API, as well as the machine readable Postman environment files for the virtualized and production environments.
I am reworking my API catalog currently, where I possess almost 100,000 individual API definitions for APIs across several thousand API providers. I used to host all of these across many different GitHub repositories within a single organization, but I am rethinking how I publish them using GitHub. I’m considering either going with a single mono-repo for my API discovery catalog, or maybe break down by category within a single GitHub organization. Ultimately I want to provide a blueprint for other API providers to follow when publishing their own machine readable API definitions to GitHub, and manage the API definitions for the 3rd party API providers they depend upon.
