This is a post that has been in my API notebook for quite a while. I feel it is important to keep showcasing the growing number of API providers who are not just using OpenAPI, but also managing them on Github, so I had to make the time to talk about the email API provider SendGrid managing their OpenAPI using Github. Adding to the stack of top tier API providers managing their API definitions in this way.
SendGrid is managing announcements around their OpenAPI definition using Github, allowing developers to signup for email notifications around releases and breaking changes. You can use the Github repository to stay in tune with the API roadmap, and contribute feature requests, submit bug reports, and even submit a pull request with the changes you’d like to see. Going beyond just an API definition being about API documentation, and actually driving the API road map and feedback loop.
This approach to managing an API definition, while also making it a centerpiece of the feedback loop with your community is why I keep beating this drum, and showcasing API providers who are doing this. It is a way to manage the central API contract, where the platform provider and API consumers both have a voice, and producing a machine readable artifact that can be then used across the API lifecycle, from design to deprecation. Elevating the API definition beyond just a bi-product of creating API docs, and making it a central actor in everything that occurs as part of API operations.
I’m still struggling with convincing API providers that they should be adopting OpenAPI. That it is much more than an artifact driving interactive documentation. Showcasing companies like SendGrid using OpenAPI, as well as their usage of Github, is an important part of me convincing other API providers to do the same. If you want me to write about your API, and what you are working to accomplish with your API resources, then publish your OpenAPI definition to Github, and engage with your community there. It may take me a few months, but eventually I will get around to writing it up, and incorporating your story into my toolbox for changing behavior in our API community.
