OpenAPI is a standard for de­scrib­ing computing in­ter­faces known as APIs (Ap­plic­a­tion Pro­gram­ming In­ter­faces). The OpenAPI Spe­cific­a­tion defines an open, vendor-neutral de­scrip­tion format for API services. OpenAPI allows de­velopers to describe, develop, test, and document REST-compliant APIs.

The OpenAPI Spe­cific­a­tion resulted from the Swagger project. De­vel­op­ment company SmartBear decided to make the Swagger Spe­cific­a­tion available under an open-source licence and handed over its main­ten­ance and further de­vel­op­ment to the OpenAPI Ini­ti­at­ive. As well as SmartBear, the OpenAPI Ini­ti­at­ive members include industry heavy­weights such as Google, IBM and Microsoft. The project is also sponsored by the Linux Found­a­tion.

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

OpenAPI – an overview

Many people are not sure of the dif­fer­ence between OpenAPI and Swagger. OpenAPI is a spe­cific­a­tion. In other words, it’s an abstract de­scrip­tion and isn’t linked to a specific technical im­ple­ment­a­tion. Up until Version 2.0, this spe­cific­a­tion was known as the Swagger Spe­cific­a­tion. Later, it was renamed the OpenAPI Spe­cific­a­tion. However, the tools created by the original de­velopers (SmartBear), still go by the Swagger name.

OpenAPI gives de­velopers a stand­ard­ised way of de­scrib­ing APIs. The de­scrip­tion is referred to as the ‘API defin­i­tion’ and is generated in a machine-readable format. The most used languages are YAML and JSON.

Note

As well as ‘API defin­i­tion’, you may also come across the term ‘API spe­cific­a­tion’. Both are abstract de­scrip­tions of an API, but the latter is produced ex­clus­ively for human readers.

From a technical point of view, there is little dif­fer­ence between YAML and JSON, so an API defin­i­tion in one language can auto­mat­ic­ally 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 spe­cific­a­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­form­a­tion for the API provider
  • Licence Object: Licence 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­pon­ents Object: Re-usable com­pon­ents which can be used more than once within an API defin­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 para­met­ers and the expected server responses for an operation

Where is OpenAPI used?

In general, OpenAPI is used to describe REST APIs in a stand­ard­ised manner. By making the de­scrip­tion (the API defin­i­tion) available in a machine-readable format, various virtual artifacts can be auto­mat­ic­ally generated from it. This includes:

  • API doc­u­ment­a­tion: HTML-based doc­u­ment­a­tion can be auto­mat­ic­ally generated from the machine-readable API defin­i­tion. De­velopers working with the API services can then use this as reference doc­u­ment­a­tion. If the API defin­i­tion is changed, the doc­u­ment­a­tion is re­gen­er­ated so that it reflects the latest defin­i­tion.
  • Code in various pro­gram­ming languages: Using a special tool, a client-side software library can be generated from the API defin­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­teg­rated in the usual way. The API services can then be accessed via function call-ups in the normal pro­gram­ming en­vir­on­ment.
  • Test cases: Every component in a piece of software has to be tested to make sure that it works correctly. Moreover, software com­pon­ents have to be re-tested whenever the un­der­ly­ing code is modified. Thanks to the API defin­i­tion, these test cases can be auto­mat­ic­ally generated so that the functions of the software com­pon­ents can be checked thor­oughly.

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­vant­ages of OpenAPI?

In summary, the advantage of OpenAPI is that it allows de­velopers to keep the im­ple­ment­a­tion, doc­u­ment­a­tion and testing of an API con­sist­ent through­out its de­vel­op­ment and ongoing main­ten­ance. Fur­ther­more, using the OpenAPI spe­cific­a­tion allows for better backend/frontend co­ordin­a­tion during the de­vel­op­ment of the API. Code com­pon­ents can be generated from the API defin­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­larly useful in that it provides a stand­ard­ised way of de­vel­op­ing REST APIs. This is very useful, because although REST-compliant APIs have several ad­vant­ages, 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­pend­ently 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 defin­i­tion using ap­pro­pri­ate tools
  • Creating in­ter­act­ive API doc­u­ment­a­tion
  • Allowing both people and machines to un­der­stand and learn about the cap­ab­il­it­ies of a service without having to study the source code or ad­di­tion­al doc­u­ment­a­tion
  • Accessing API services with minimal im­ple­ment­a­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 Spe­cific­a­tion No longer used
2.0, September 2014 Swagger Spe­cific­a­tion > OpenAPI Spe­cific­a­tion Still supported
3.0, July 2017 OpenAPI Spe­cific­a­tion Still supported
Image: OpenAPI versions: Structural differences between OpenAPI v2.0 and v3.0
Overall, the structure of the OpenAPI spe­cific­a­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­pon­ents Object and Reference Object

One of the most important new features in OpenAPI version 3.0 is the addition of the Com­pon­ents Object and the Reference Object. The Com­pon­ents Object allows de­velopers to define multiple objects that can be reused within the API defin­i­tion. Known as com­pon­ents, these are in­teg­rated in the API defin­i­tion using the special construct $ref.

Thanks to the com­pon­ents and ref­er­ences, an API defin­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 defin­i­tion:

  1. Schema of a GitHub code re­pos­it­ory defined as a Com­pon­ents Object
  2. Licence defin­i­tion ref­er­enced via an ex­tern­ally 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"
                },
                // Licence Definition
                "licence": {
                    "nullable": true,
                    "allOf": [
                        {
                            // Reference to externally defined components
                            "$ref": "#/components/schemas/license-simple"
                        }
                    ]
                },

Using OpenAPI: Two examples

The OpenAPI spe­cific­a­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 defin­i­tion is available on GitHub as a re­pos­it­ory. It allows users to identify exactly which services can be accessed via the GitHub API and how the cor­res­pond­ing calls have to be struc­tured. Fur­ther­more, anyone can use the API along with com­pat­ible tools to generate code for it.

According to GitHub, the API defin­i­tion is used to describe, create, consume, and visualise the REST API. At the time of writing, the API defin­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 spe­cific­a­tion.

For com­pat­ib­il­ity reasons, GitHub provides the API defin­i­tion in several formats. One of these is a ‘bundled’ version. This contains the com­pon­ents in­tro­duced using OpenAPI 3.0 and the ref­er­ences to them. Al­tern­at­ively, there is a ‘derefer­enced’ version, without any ref­er­ences. Due to re­dund­ancy, the derefer­enced API defin­i­tion is around three times larger than the bundled version. However, this derefer­enced version is very useful because many tools do not yet support ref­er­ences.

You can study the API defin­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­form­a­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­form­a­tion, terms of use, license, etc.
  • The API endpoints and the op­er­a­tions of each endpoint
  • The permitted input and output para­met­ers of the op­er­a­tions
  • Security spe­cific­a­tions

You can learn a lot about how OpenAPI works by examining the petstore API. The petstore defin­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­vidu­ally defined OpenAPI com­pon­ents.

# 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