What is OpenAPI and how does it help REST API.

Imagine it's your first day at work as a Software Developer working for an Investment Bank.

It's your job to understand the bank's different systems and services.
Now you don't understand the different REST APIs being used and what they do.

You also do not want to go through the whole codebase of these APIs.
What will you do??

You will refer to the OpenAPI document to quickly understand what your REST APIs do.

The OpenAPI Specification (OAS) is the universal standard to define and read RESTful APIs for humans as well as computers.

It helps you understand your API without having to read the source code or documentation.

The OpenAPI definition is typically a YAML/JSON file.

With an OpenAPI definition, you can describe the following things:
1) Properties, Data types
2) Endpoints
3) Auth and many more..
It also helps in validating new APIs that are being built.

An OpenAPI doc can be programmatically generated from your code using multiple tools like Swagger.
It is often used to test APIs and generate client code.

Here is an example of an OpenAPI doc:

Keywords used in the doc and what they mean:

1. info : The info section contains API information: title, description (optional), version.
2. servers: specifies the API server and base URL.
3. paths: defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints.
4. parameters: they are passed via URL path, query string, headers. You can define the parameter data types, format, whether they are required or optional, and other details.
5. requestBody: describes the body content and media type.

Hope you liked this short explainer.
You can also find my threads on various backend concepts from the Web2 and Web3 world on Twitter