Open API

What is Open API?

Open API is a specification created to govern the interactions between REST APIs. While REST itself is a series of architectural best practices, Open API is a specification that ["defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection" (source).  

What problem does the Open API spec solve?

Imagine all the coding languages you've heard of- Python, Go, Ruby, etc. They all have unique grammar and syntax. Before the rise of web services, an application could exist in one place, in one language, and be fine. Now, applications exist on multiple containers across multiple databases, and communicate with each other through REST APIs endpoints. These applications need to not only work with other applications, but to be documented in an intuitive way so programmers can use them. The Open API spec solves this problem by forcing developers to build, define, and document their REST APIs in a standardized way.

Does Open API spec work with the JSON schema draft?

Open API Spec 3 has "full alignment of OpenAPI 3.1.0 with JSON Schema draft 2020-12". This was an important development because the two specifications didn't always play well together, and was a consistent pain point for API developers. With the standards working together, there is great progress towards a single source of truth in the already complex world of REST API.

What can I do with Open API?

A sample Open API YAML file looks like this:

openapi: 
info:
  version: 
  title: Sample API
  description: A sample API to illustrate OpenAPI concepts 
paths:
  /list:
    get:
      description: Returns a list of stuff              
      responses:
        '200':
          description: Successful response
        '404':,
          description: Unsuccessful response

With just a few lines of code, we've defined an API endpoint in a functional and clear way. Another programmer on the other side of the world could understand what work is being done here. We can also automatically output our endpoints into our software documentation, because the Open API defines fields consistently.  

What's going on in this YAML file?

YAML syntax is a lightweight, easy-to-read language commonly seen in configuration files. This configuration files shows us that we are using Open API spec, a description of what the API does, and the path and endpoints the developer interacts with. The `responses` field defines HTTP codes for responses. A `200` indicates a success, and a `404` indicates a failure.  

Conclusion

Open API is a powerful standard, and has been helpful in defining and standardizing the chaotic world of web development. The nature of REST APIs- being able to get a key and use an API, without any human contact- means working together without always having the luxury of asking "What does this endpoint do?" or "What kind of response can I expect?", and the Open API Spec solves that problem.