From 0 to OpenAPI: How GitHub Described a 10 year old API

By September 22, 2020Blog

GitHub recently adjusted their extensive, old API in order to comply with current OpenAPI standards. At the API Specifications Conference we got the opportunity to hear how they accomplished this feat from leaders on the project.

GitHub recently released an OpenAPI description for their REST API. It is now easier than ever to integrate projects with GitHub data using simple, standardized API calls. However, the API team at GitHub faced many challenges in describing their massive API so that it would comply with OpenAPI specifications. At one point, their API had over 37,000 errors and 500 invalid operators!

The enthralling explanation of their unique solutions to these challenges is available here.

A quick description of the OpenAPI Specification:

  • “The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.”

GitHub adopted OpenAPI specifications for their API in order to automate SDK’s and documentation. Using OpenAPI descriptions also helps ensure a consistent developer experience for users of the API. Finally, implementation of an OpenAPI description simplifies and standardizes the system, freeing up GitHub’s API team to work on other aspects of the project. 

GitHub Open Source REST API is available at the link below: 

https://github.com/github/rest-api-description

GitHub REST API Documentation: 

https://docs.github.com/en/rest/overview/resources-in-the-rest-api