RESTFUL API’s have been around for a while. And every year, more and more software projects start using them. They allow you to create an easy and consistent way to connect one or multiple clients to your services. And they allow you to make certain resources publicly available to other developers so that they can integrate with them.

Image via readme.com

It’s great that we have access to all these APIs. But there are often times issues and misunderstandings when integrating with them. So, with all of these API’s being developed, the need for a standard grew. This brings us to OpenAPI.

What is OpenAPI

In their own words:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST 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. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

– OpenAPI

Basically, it’s a standardized way of describing an API using JSON or YAML. When done right, you can give a person access to your OpenAPI document, and they can start developing an integration, without ever having made a request to your server or having to read docs.

Tools and resources

There are so many tools to begin using OpenAPI. I personally use stoplight to help me write OpenAPI documents. I’ve found it to be very easy. There is also Swagger.

You can read more on OpenAPI here.