What is OpenAPI?
IONOS editorial team
OpenAPI is a standard for describing computing interfaces known as APIs (Application Programming Interfaces). The OpenAPI Specification defines an open, vendor-neutral description format for API services. OpenAPI allows developers to describe, develop, test, and document REST-compliant APIs.
The OpenAPI Specification resulted from the Swagger project. Development company SmartBear decided to make the Swagger Specification available under an open-source license and handed over its maintenance and further development to the OpenAPI Initiative. As well as SmartBear, the OpenAPI Initiative members include industry heavyweights such as Google, IBM and Microsoft. The project is also sponsored by the Linux Foundation.
- DNS management
- Easy SSL admin
- API documentation
OpenAPI – an overview
Many people are not sure of the difference between OpenAPI and Swagger. OpenAPI is a specification. In other words, it’s an abstract description and isn’t linked to a specific technical implementation. Up until Version 2.0, this specification was known as the Swagger Specification. Later, it was renamed the OpenAPI Specification. However, the tools created by the original developers (SmartBear), still go by the Swagger name.
OpenAPI gives developers a standardized way of describing APIs. The description is referred to as the “API definition” and is generated in a machine-readable format. The most used languages are YAML and JSON.
As well as “API definition”, you may also come across the term “API specification”. Both are abstract descriptions of an API, but the latter is produced exclusively for human readers.
From a technical point of view, there is little difference between YAML and JSON, so an API definition in one language can automatically 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 specification defines several properties which are used to create an API. These properties 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 information 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
- Components Object: Re-usable components which can be used more than once within an API definition
- Paths Object: Relative paths to the endpoints of the API, which are used in conjunction with the Server Object
- Path Item Object: Operations permitted for a specific path, such as GET, PUT, POST, DELETE
- Operation Object: Defines (among other things) the parameters and the expected server responses for an operation
Where is OpenAPI used?
In general, OpenAPI is used to describe REST APIs in a standardized manner. By making the description (the API definition) available in a machine-readable format, various virtual artifacts can be automatically generated from it. This includes:
- API documentation: HTML-based documentation can be automatically generated from the machine-readable API definition. Developers working with the API services can then use this as reference documentation. If the API definition is changed, the documentation is regenerated so that it reflects the latest definition.
- Code in various programming languages: Using a special tool, a client-side software library can be generated from the API definition in a supported programming language. This means that programmers from all kinds of backgrounds can access the API. The software library is integrated in the usual way. The API services can then be accessed via function call-ups in the normal programming environment.
- Test cases: Every component in a piece of software has to be tested to make sure that it works correctly. Moreover, software components have to be re-tested whenever the underlying code is modified. Thanks to the API definition, these test cases can be automatically generated so that the functions of the software components can be checked thoroughly.
For the sake of completeness, it should be noted that not every API can be defined using OpenAPI. However, there is explicit support for REST APIs.
What are the advantages of OpenAPI?
In summary, the advantage of OpenAPI is that it allows developers to keep the implementation, documentation and testing of an API consistent throughout its development and ongoing maintenance. Furthermore, using the OpenAPI specification allows for better backend/frontend coordination during the development of the API. Code components can be generated from the API definition on both sides, meaning that both backend and frontend teams can carry out development, and testing without having to wait for one another.
As well as these overall benefits, OpenAPI is particularly useful in that it provides a standardized way of developing REST APIs. This is very useful, because although REST-compliant APIs have several advantages, developing 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 independently of a specific programming language
- Generating server code for an API defined in OpenAPI
- Generating client-side libraries for an OpenAPI-compliant API in more than 40 programming languages
- Editing an OpenAPI definition using appropriate tools
- Creating interactive API documentation
- Allowing both people and machines to understand and learn about the capabilities of a service without having to study the source code or additional documentation
- Accessing API services with minimal implementation effort
How many OpenAPI versions are there and what’s the difference 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 Specification | No longer used |
| 2.0, September 2014 | Swagger Specification > OpenAPI Specification | Still supported |
| 3.0, July 2017 | OpenAPI Specification | Still supported |
The paragraphs 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 Components Object and Reference Object
One of the most important new features in OpenAPI version 3.0 is the addition of the Components Object and the Reference Object. The Components Object allows developers to define multiple objects that can be reused within the API definition. Known as components, these are integrated in the API definition using the special construct $ref.
Thanks to the components and references, an API definition 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 definition:
- Schema of a GitHub code repository defined as a Components Object
- License definition referenced via an externally 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 specification and the related tools, in particular 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 definition is available on GitHub as a repository. It allows users to identify exactly which services can be accessed via the GitHub API and how the corresponding calls have to be structured. Furthermore, anyone can use the API along with compatible tools to generate code for it.
According to GitHub, the API definition is used to describe, create, consume, and visualize the REST API. At the time of writing, the API definition 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 operations can be run via different paths, whereas only one path is indicated in the specification.
For compatibility reasons, GitHub provides the API definition in several formats. One of these is a “bundled” version. This contains the components introduced using OpenAPI 3.0 and the references to them. Alternatively, there is a “dereferenced” version, without any references. Due to redundancy, the dereferenced API definition is around three times larger than the bundled version. However, this dereferenced version is very useful because many tools do not yet support references.
You can study the API definition yourself. Note, however, that the complete file is several megabytes in size. For a text file, that’s a huge amount of information. 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 SwaggerHub
This second example is a sample API that can be generated on SwaggerHub. SwaggerHub is an online platform for designing and developing 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 information, terms of use, license, etc.
- The API endpoints and the operations of each endpoint
- The permitted input and output parameters of the operations
- Security specifications
You can learn a lot about how OpenAPI works by examining the petstore API. The petstore definition 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:
- It defines the API endpoint '/pet'.
- Using a HTTP POST request, you can add a new animal to the petstore.
- If you use the HTTP verb PUT instead, on the same endpoint, you can modify an existing animal.
- Different server responses are defined for the operations. 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”.
The lines of code which begin with '$ref' and are commented with “OpenAPI 3.0+ Component” are references to individually defined OpenAPI components.
# 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'OpenAPI has established itself as an open, vendor-neutral description format for API services. It seems likely that OpenAPI will be widely used as a standard for building REST APIs in the foreseeable future.
