OpenAPI is a standard for de­scrib­ing computing in­ter­faces known as APIs (Ap­pli­ca­tion Pro­gram­ming In­ter­faces). The OpenAPI Spec­i­fi­ca­tion defines an open, vendor-neutral de­scrip­tion format for API services. OpenAPI allows de­vel­op­ers to describe, develop, test, and document REST-compliant APIs.

The OpenAPI Spec­i­fi­ca­tion resulted from the Swagger project. De­vel­op­ment company SmartBear decided to make the Swagger Spec­i­fi­ca­tion available under an open-source license and handed over its main­te­nance and further de­vel­op­ment to the OpenAPI Ini­tia­tive. As well as SmartBear, the OpenAPI Ini­tia­tive members include industry heavy­weights such as Google, IBM and Microsoft. The project is also sponsored by the Linux Foun­da­tion.

IONOS Developer API
Manage your hosting products through our powerful API
  • DNS man­age­ment
  • Easy SSL admin
  • API doc­u­men­ta­tion

OpenAPI – an overview

Many people are not sure of the dif­fer­ence between OpenAPI and Swagger. OpenAPI is a spec­i­fi­ca­tion. In other words, it’s an abstract de­scrip­tion and isn’t linked to a specific technical im­ple­men­ta­tion. Up until Version 2.0, this spec­i­fi­ca­tion was known as the Swagger Spec­i­fi­ca­tion. Later, it was renamed the OpenAPI Spec­i­fi­ca­tion. However, the tools created by the original de­vel­op­ers (SmartBear), still go by the Swagger name.

OpenAPI gives de­vel­op­ers a stan­dard­ized way of de­scrib­ing APIs. The de­scrip­tion is referred to as the “API de­f­i­n­i­tion” and is generated in a machine-readable format. The most used languages are YAML and JSON.

Note

As well as “API de­f­i­n­i­tion”, you may also come across the term “API spec­i­fi­ca­tion”. Both are abstract de­scrip­tions of an API, but the latter is produced ex­clu­sive­ly for human readers.

From a technical point of view, there is little dif­fer­ence between YAML and JSON, so an API de­f­i­n­i­tion in one language can au­to­mat­i­cal­ly be converted to the other. However, YAML has a clearer structure and is easier for humans to read. Here’s an example of an OpenAPI Server Object, first in YAML, then in JSON:

# YAML
servers:
- url: https://development.example.com/v1
    description: Development server
- url: https://staging.example.com/v1
    description: Staging server
- url: https://api.example.com/v1
    description: Production server
// JSON
{
    "servers": [
        {
            "url": "https://development.example.com/v1",
            "description": "Development server"
        },
        {
            "url": "https://staging.example.com/v1",
            "description": "Staging server"
        },
        {
            "url": "https://api.example.com/v1",
            "description": "Production server"
        }
    ]
}

The OpenAPI spec­i­fi­ca­tion defines several prop­er­ties which are used to create an API. These prop­er­ties are grouped together as “objects”. The current version of OpenAPI (3.0.3) defines the structure for the following objects (among others):

  • Info Object: API version, name, etc.
  • Contact Object: Contact in­for­ma­tion for the API provider
  • License Object: License under which the API provides its data
  • Server Object: Host name, URL structure, and ports of the server through which the API is accessed
  • Com­po­nents Object: Re-usable com­po­nents which can be used more than once within an API de­f­i­n­i­tion
  • Paths Object: Relative paths to the endpoints of the API, which are used in con­junc­tion with the Server Object
  • Path Item Object: Op­er­a­tions permitted for a specific path, such as GET, PUT, POST, DELETE
  • Operation Object: Defines (among other things) the pa­ra­me­ters and the expected server responses for an operation

Where is OpenAPI used?

In general, OpenAPI is used to describe REST APIs in a stan­dard­ized manner. By making the de­scrip­tion (the API de­f­i­n­i­tion) available in a machine-readable format, various virtual artifacts can be au­to­mat­i­cal­ly generated from it. This includes:

  • API doc­u­men­ta­tion: HTML-based doc­u­men­ta­tion can be au­to­mat­i­cal­ly generated from the machine-readable API de­f­i­n­i­tion. De­vel­op­ers working with the API services can then use this as reference doc­u­men­ta­tion. If the API de­f­i­n­i­tion is changed, the doc­u­men­ta­tion is re­gen­er­at­ed so that it reflects the latest de­f­i­n­i­tion.
  • Code in various pro­gram­ming languages: Using a special tool, a client-side software library can be generated from the API de­f­i­n­i­tion in a supported pro­gram­ming language. This means that pro­gram­mers from all kinds of back­grounds can access the API. The software library is in­te­grat­ed in the usual way. The API services can then be accessed via function call-ups in the normal pro­gram­ming en­vi­ron­ment.
  • Test cases: Every component in a piece of software has to be tested to make sure that it works correctly. Moreover, software com­po­nents have to be re-tested whenever the un­der­ly­ing code is modified. Thanks to the API de­f­i­n­i­tion, these test cases can be au­to­mat­i­cal­ly generated so that the functions of the software com­po­nents can be checked thor­ough­ly.

For the sake of com­plete­ness, it should be noted that not every API can be defined using OpenAPI. However, there is explicit support for REST APIs.

What are the ad­van­tages of OpenAPI?

In summary, the advantage of OpenAPI is that it allows de­vel­op­ers to keep the im­ple­men­ta­tion, doc­u­men­ta­tion and testing of an API con­sis­tent through­out its de­vel­op­ment and ongoing main­te­nance. Fur­ther­more, using the OpenAPI spec­i­fi­ca­tion allows for better backend/frontend co­or­di­na­tion during the de­vel­op­ment of the API. Code com­po­nents can be generated from the API de­f­i­n­i­tion on both sides, meaning that both backend and frontend teams can carry out de­vel­op­ment, and testing without having to wait for one another.

As well as these overall benefits, OpenAPI is par­tic­u­lar­ly useful in that it provides a stan­dard­ized way of de­vel­op­ing REST APIs. This is very useful, because although REST-compliant APIs have several ad­van­tages, de­vel­op­ing one manually is not that easy. REST runs over HTTP/S, and the necessary ports are open in all firewalls.

Other useful features of OpenAPI include:

  • Defining HTTP APIs in­de­pen­dent­ly of a specific pro­gram­ming language
  • Gen­er­at­ing server code for an API defined in OpenAPI
  • Gen­er­at­ing client-side libraries for an OpenAPI-compliant API in more than 40 pro­gram­ming languages
  • Editing an OpenAPI de­f­i­n­i­tion using ap­pro­pri­ate tools
  • Creating in­ter­ac­tive API doc­u­men­ta­tion
  • Allowing both people and machines to un­der­stand and learn about the ca­pa­bil­i­ties of a service without having to study the source code or ad­di­tion­al doc­u­men­ta­tion
  • Accessing API services with minimal im­ple­men­ta­tion effort

How many OpenAPI versions are there and what’s the dif­fer­ence between them?

At the time of writing, the latest version of OpenAPI is 3.0.3. Here is a brief overview of the previous versions:

Version Name Status
1.0, August 2011 Swagger Spec­i­fi­ca­tion No longer used
2.0, September 2014 Swagger Spec­i­fi­ca­tion > OpenAPI Spec­i­fi­ca­tion Still supported
3.0, July 2017 OpenAPI Spec­i­fi­ca­tion Still supported
Image: OpenAPI versions: Structural differences between OpenAPI v2.0 and v3.0
Overall, the structure of the OpenAPI spec­i­fi­ca­tion has been trimmed down

The para­graphs below explain the main new features added in version 3.0:

New name for the root object

With the release of version 3.0, the Swagger object was replaced by the OpenAPI object:

# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"

Multiple hosts/server

In OpenAPI 3.0, an API can be addressed via more than one server. It’s also possible to define parts of a server URL as variables. For example:

"servers": [
        {
            "url": "https://{username}.example.com:{port}/{basePath}",
            "description": "The production API server",
            "variables": {
                "username": {
                    "default": "demo",
                    "description": "this value is assigned by the service provider, in this example `example.com`"
                },
                "port": {
                    "enum": [
                        "8443",
                        "443"
                    ],
                    "default": "8443"
                },
                "basePath": {
                    "default": "v2"
                }
            }
        }
    ]

New Com­po­nents Object and Reference Object

One of the most important new features in OpenAPI version 3.0 is the addition of the Com­po­nents Object and the Reference Object. The Com­po­nents Object allows de­vel­op­ers to define multiple objects that can be reused within the API de­f­i­n­i­tion. Known as com­po­nents, these are in­te­grat­ed in the API de­f­i­n­i­tion using the special construct $ref.

Thanks to the com­po­nents and ref­er­ences, an API de­f­i­n­i­tion can be built from several re-usable parts. This makes it easier to read and reduces the size of the overall document. The following OpenAPI example is taken from the official GitHub API de­f­i­n­i­tion:

  1. Schema of a GitHub code repos­i­to­ry defined as a Com­po­nents Object
  2. License de­f­i­n­i­tion ref­er­enced via an ex­ter­nal­ly defined component
"components": {
    "schemas": {
        // Repository Schema
        "repository": {
            "title": "Repository",
            "description": "A git repository",
            "type": "object",
            "properties": {
                "id": {
                    "description": "Unique identifier of the repository",
                    "example": 42,
                    "type": "integer"
                },
                "node_id": {
                    "type": "string",
                    "example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
                },
                "name": {
                    "description": "The name of the repository.",
                    "type": "string",
                    "example": "Team Environment"
                },
                "full_name": {
                    "type": "string",
                    "example": "octocat/Hello-World"
                },
                // License Definition
                "license": {
                    "nullable": true,
                    "allOf": [
                        {
                            // Reference to externally defined components
                            "$ref": "#/components/schemas/license-simple"
                        }
                    ]
                },

Using OpenAPI: Two examples

The OpenAPI spec­i­fi­ca­tion and the related tools, in par­tic­u­lar Swagger, are used to create all kinds of API. Here are two examples.

GitHub v3 REST API

The popular Git service, GitHub, uses OpenAPI to describe its “GitHub v3 REST API”. The API de­f­i­n­i­tion is available on GitHub as a repos­i­to­ry. It allows users to identify exactly which services can be accessed via the GitHub API and how the cor­re­spond­ing calls have to be struc­tured. Fur­ther­more, anyone can use the API along with com­pat­i­ble tools to generate code for it.

According to GitHub, the API de­f­i­n­i­tion is used to describe, create, consume, and visualize the REST API. At the time of writing, the API de­f­i­n­i­tion is not complete. Some header fields are missing for example, but these should be added in the future. Also, note that some of the possible API op­er­a­tions can be run via different paths, whereas only one path is indicated in the spec­i­fi­ca­tion.

For com­pat­i­bil­i­ty reasons, GitHub provides the API de­f­i­n­i­tion in several formats. One of these is a “bundled” version. This contains the com­po­nents in­tro­duced using OpenAPI 3.0 and the ref­er­ences to them. Al­ter­na­tive­ly, there is a “deref­er­enced” version, without any ref­er­ences. Due to re­dun­dan­cy, the deref­er­enced API de­f­i­n­i­tion is around three times larger than the bundled version. However, this deref­er­enced version is very useful because many tools do not yet support ref­er­ences.

You can study the API de­f­i­n­i­tion yourself. Note, however, that the complete file is several megabytes in size. For a text file, that’s a huge amount of in­for­ma­tion. GitHub cannot display such a large file directly. However, via the link below you can view the GitHub REST API in your browser. This is a YAML version and is much more compact and easier to read: GitHub REST API (YAML).

Petstore example API from Swag­ger­Hub

This second example is a sample API that can be generated on Swag­ger­Hub. Swag­ger­Hub is an online platform for designing and de­vel­op­ing REST APIs using OpenAPI. You can either create a free user account or use an existing GitHub account.

Once you’ve logged in, you’re ready to create a new API. There’s an option to use an existing template, for example, an API template for an online petstore. The petstore API generated using this template includes a wide range of API objects, including:

  • Contact in­for­ma­tion, terms of use, license, etc.
  • The API endpoints and the op­er­a­tions of each endpoint
  • The permitted input and output pa­ra­me­ters of the op­er­a­tions
  • Security spec­i­fi­ca­tions

You can learn a lot about how OpenAPI works by examining the petstore API. The petstore de­f­i­n­i­tion is also a good example of how to build a REST-compliant API. Finally, let’s take a look at some code from the petstore API:

  1. It defines the API endpoint '/pet'.
  2. Using a HTTP POST request, you can add a new animal to the petstore.
  3. If you use the HTTP verb PUT instead, on the same endpoint, you can modify an existing animal.
  4. Different server responses are defined for the op­er­a­tions. In this example, the HTTP status codes include the well-known “404 Not Found” error. In the petstore API, this is presented as “Pet not found”.
Note

The lines of code which begin with '$ref' and are commented with “OpenAPI 3.0+ Component” are ref­er­ences to in­di­vid­u­al­ly defined OpenAPI com­po­nents.

# Petstore API Template #
# API Endpoint '/pet'
/pet:
    # HTTP-POST Request
    post:
        tags:
            - pet
        summary: Add a new pet to the store
        operationId: addPet
        # HTTP-Status codes
        responses:
            '405':
                description: Invalid input
        security:
            # Permissions
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        requestBody:
            # OpenAPI 3.0+ Component
            $ref: '#/components/requestBodies/Pet'
    # HTTP-PUT Request
    put:
        tags:
            - pet
        summary: Update an existing pet
        operationId: updatePet
        # HTTP-Status codes
        responses:
            '400':
                description: Invalid ID supplied
            '404':
                description: Pet not found
            '405':
                description: Validation exception
        security:
            # Permissions
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        requestBody:
            # OpenAPI 3.0+ Component
            $ref: '#/components/requestBodies/Pet'
Summary

OpenAPI has es­tab­lished itself as an open, vendor-neutral de­scrip­tion format for API services. It seems likely that OpenAPI will be widely used as a standard for building REST APIs in the fore­see­able future.

Go to Main Menu