DEV Community

Cover image for What is OpenAPI and how does it help REST API.
Pratim Bhosale
Pratim Bhosale

Posted on

4 2

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:

OpenAPI specification example document

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

API Trace View

How I Cut 22.3 Seconds Off an API Call with Sentry

Struggling with slow API calls? Dan Mindru walks through how he used Sentry's new Trace View feature to shave off 22.3 seconds from an API call.

Get a practical walkthrough of how to identify bottlenecks, split tasks into multiple parallel tasks, identify slow AI model calls, and more.

Read more →

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more