First Look into Github's OpenAPI Description

The original post was on First Look into Github's OpenAPI Description - Reading Time: 4 Mins and cover image by Photo by Denny Müller on Unsplash

Introduction

When it comes to API development, my goto blog has always been API Evangelist. Which Kin Lane who is better known as API Evangelist currently is the chief evangelist for Postman. It is due to his writings and tons of research that lead me to understand alot about what should be considered good practice in developing an API.

As I dive deeper into it, I start to understand why is there a need to learn about it. Especially the ecosystem surrounding it goes beyond just the simple hello world version of a POST or GET requests. It serves as a communication, between multiple different people who might be using it. From a developer who is integrating API for a new service to product or operations team who deals with onboarding & tracking of API services. It could also be an entrepreneur who is looking into building their own SasS company to make it easy for a developer or anyone to adopt it.

What is OpenAPI?

OpenAPI is a set of API design specification standard that is used by alot of companies or organisations. It was previously known as Swagger by Smartbear. Who donated the API Specification to the Linux Foundation and created the OpenAPI Initiative.

Which tons of companies or organisations use it to document their APIs or to provide a rundown on how an API will work. From calling it to creating API mockup before any actual API development is carried out. This serves two purposes.

The first acts as a form of contract between the API provider & consumer of the API service. For what is expected in the API. The second is to use it as a single source of truth. Where everyone has a common understanding of the API from the front-end developer & back-end developer. Which allows them to operate independently with just an API mockup based upon the OpenAPI specification.

Without depending for each other to get ready to test and built upon an API. While I was seeking to frantically develop & provide an API. For my front-end developer or other stakeholders. Who was breathing down my neck to have the API built & deployed for them to test or use it.

What is Github OpenAPI Description?

To be honest, I know that GitHub is one of the few companies that adopt more of an API first approach to their API services but I did not look at it in detail because I do not use it for my end in my work.

Which GitHub focus on building API by thinking deeply on the design, adoption, development, deployment, evangelism of the APIs for Developers like you or me. Create products or services on top of it to form an ecosystem. Think of companies like Travis CI, CodeSandBox, Zapier. Which are some of the services that use it and built on top of these APIs.

What caught me the most is that GitHub has started to transit towards the use of OpenAPI standard to document and showcase their 600 operations of their APIs to developers. Instead of continuing rolling their own API style. Like alot of companies that tend to provide it. Which can be painful & time-consuming, if you are unable to understand, test or interact how their API work.

Some of the Useful API Points for a Developer

Due to its extensive nature of about 600 operations covered by GitHub in their OpenAPI Description. I won't be listing but those that look interesting to me of their categories. So here it goes:

• Actions - Provides ways for you to automate your development workflow.

• Activities - Provides alerts and notifications on your repository that is read-only events

• Issues - Deals with the management of issues under the user or the user's organisation he/she belongs to.

• Projects - Provides an overview of the management of a project board. You can understand the difference between Project and Repository.

• Repository - The management of repository. Which bulk of your API calls comes from as an individual user or organisation.

Conclusion

For GitHub transition, their API documentation into OpenAPI can be quite a big deal. Since they are one of the early adopters of GraphQL. Which lead to tons of developers looking to integrate it. As part of their approach to creating APIs for their React, Vue or Angular front-end. Which trickles down to mobile app development as well. So with GitHub playing a role in transiting their API documentation to OpenAPI.

Which is considered as part of one of the few industry-standard like Stripe, Twilio, SalesForce. Even before their move towards OpenAPI. I believe that there will be more and more developers. Who will be talking about it and using the OpenAPi Standard. As part of their goto API design & documentation inspiration. When they are looking at building an API instead of just doing it in their own way.

If you like this article do sign up for my Adventurer's Newsletter. Which contains interesting content I stumble across over the week in the area of Python, Web Development, Startup and articles that I wrote.

You can also follow me to get the latest update of my article on Dev.

Lastly, are you looking to specialise yourself as a developer? If it's a Yes. I'm giving away my free ebook called "Picking Your Specialisation as a Developer" for anyone interested to command a higher salary or do the work that you like.

Reference

• API Evangelist
• OpenAPI
• Github OpenAPI Description
• Swagger
• What Is OpenAPI?
• Smartbear
• OpenAPI Initiative
• API first
• Travis CI
• CodeSandBox
• Zapier
• Introducing Github OpenAPI Description
• OpenAPI Description Repository
• Actions
• Activities
• Issues
• Projects
• Project and Repository
• Repository
• Best Practices in API Governace
• API Lifecycle and Governance in the Enterprise: Plan Stage (Part 1 of 3)
• GitHub REST API Documentation
• UnDraw