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.
Frequently Asked Questions
What is an Open API?
Open API is a specification that defines a standard, language-agnostic interface to RESTful APIs. It lets both humans and computers discover and understand what a service does without access to its source code or documentation.
How does the OpenAPI specification work?
You describe your REST API in a configuration file, typically written in YAML or JSON. That file defines the API's paths, endpoints, request and response structures, and HTTP status codes in a consistent format that both people and machines can read.
What is the difference between Open API and a REST API?
REST is a set of architectural best practices for building APIs, while Open API is a specification that governs how those REST APIs are built, defined, and documented. In short, REST describes the style and Open API standardizes the description of it.
Why does the OpenAPI specification matter?
Modern applications run across many containers, databases, and programming languages that communicate through REST APIs. Open API forces a consistent way to build, define, and document those APIs, so developers anywhere can understand how a service works without reading its source code.
What does an OpenAPI document contain?
A typical OpenAPI document declares the openapi version and includes an info section with the title and version, a paths section listing the endpoints, and the operations on each path such as a get request. Each operation defines its responses, including HTTP status codes like 200 for success and 404 for failure.
How does Open API help with API documentation?
Because Open API defines fields consistently, you can automatically output your endpoints into your software documentation. OpenAPI 3.1.0 also brought full alignment with JSON Schema draft 2020-12, which improves compatibility when describing data structures.
