Skip to main content

What You Need to Know

OpenAPI

OpenAPI Site

OpenAPI Github

OpenAPI is an open and standardized specification for describing RESTful APIs, which emerged from Swagger developed by SmartBear. In 2015, the OpenAPI Initiative (OAI) was created under the Linux Foundation, and the Swagger Specification was donated to OAI, becoming the basis for what we now know as OpenAPI Specification (OAS). Since then, OpenAPI has evolved as the main standard for describing RESTful APIs.

At some point in your career you will encounter the need to better understand APIs.

APIs (Application Programming Interfaces) are interfaces that allow communication between different systems, software or components of software. They define rules and protocols that allow one system to access functionalities or data from another in a structured and secure way.

We could compare an API to a restaurant menu:

  • The menu shows what's available (services or data the system offers).
  • You (the client) place an order based on the menu (the request to the API).
  • The kitchen (the backend system) processes your order and returns the dish (the result) without you needing to know how it was prepared.

There are several types of APIs, the most used being what we call RESTful APIs which are based on the HTTP protocol and follow the REST architectural style (using methods like GET, POST, PUT, DELETE, etc).

OpenAPI and RESTful APIs are connected because OpenAPI is a specification that describes how a RESTful API should work. It provides a standard for documenting and structuring RESTful APIs, making them easier to understand, implement and consume.

alt text

The specification alone has great value and can be consumed by different tools and processes, making it useful even without a visual interface. The UI is a complement that improves the developer experience, but is not a requirement for using OpenAPI. Through this UI we can have examples like these and we can even test with the Try It Out button.

alt text

It's necessary to mitigate risks about exposing this documentation publicly, as attackers can explore the endpoints and try different types of attacks. Further ahead we'll understand how to mitigate these risks.

OpenAPI vs RESTful APIs​

  • RESTful APIs: Are an architectural style for building APIs that use the HTTP protocol and standards like:

    • Resources represented by URLs (e.g., /users, /orders).
    • HTTP methods like GET, POST, PUT, DELETE for CRUD operations.
    • Data in formats like JSON or XML.

  • OpenAPI: Is a specification used to describe RESTful APIs. It defines:

    • The available endpoints.
    • The supported HTTP methods.
    • The parameters that can be sent (query, path, headers, body).
    • The expected data types (e.g., JSON, XML).
    • The returned responses (status codes and payload structure).

Benefits of OpenAPI for RESTful APIs​

  • Automatic documentation: Tools like Swagger UI can generate interactive documentation based on OpenAPI files.
  • Standardization: Defines a clear and consistent format for designing APIs.
  • Validation: Tools can validate if an API is adhering to the defined specification.
  • Mock APIs: Allows creating fake versions of the API for development before actual implementation.
  • Code generators: Can automatically generate clients and servers in various languages.
  • Widely used in API Gateways: Most API Gateways use files that define the API with an OpenAPI configuration.
  • Agnostic: Not created for any specific technology and language.
  • Support: Backed by several major market players. Library available in practically all languages.

OpenAPI is considered the standard for describing APIs.

OpenAPI 2.0 vs 3.0​

The difference between OpenAPI 2.0 and OpenAPI 3.0 lies in significant improvements in functionality, flexibility, and the way API resources are described, so the SCHEMA was changed and we must pay attention to this. The main change was to make components more reusable, standardized and easy to define.

alt text

We will focus on studying 3.0 as this is the future.

OpenAPI in the IDE​

The specification is written in YAML or JSON files. To help write these specifications and respect the SCHEMA we have IDE plugins that help a lot. Sometimes they bring us ready-made templates to fill in. Particularly using YAML makes reading much easier besides being less verbose.

For example, we have this plugin in VSCode.

alt text

Once installed we already have it appearing on the side and when we ask to create a template it will come ready helping us even with an explorer on the side dividing the sections.

alt text

So it's not necessary to suffer that much, we can even see how the UI looks.

OpenAPI Tools​

There are several tools that help in development:

  • Converters
  • Validators
  • Editors
  • Mock Services
  • SDK Generators
  • Documentation.

A list of known tools can be found at https://tools.openapis.org/.

alt text

Swagger Hub​

We've already seen that we can use only plugins within the IDE that help us specify, but first it's good to know that SmartBear, which donated Swagger to the OpenAPI initiative, has several commercial and open source tools that facilitate API development through Swagger Hub.

To learn, if it makes your life easier, you can make a free account just for yourself, since it's free only for 1 person. Swagger Hub has a set of tools including an editor.