externalDocs:
description: Learn more about user operations provided by this API.
url: http://api.api-portal.io/docs/user-operations/OpenAPI Specification (OAS)
The open and vendor-neutral interface description for future-oriented applications.
August 12, 2019 | 7 Min.The now high level of networking and digitization in business, industry, administration and the private sector also requires increasingly high-quality services and requirements for software structures. Data-based ecosystems and platforms now use complex and powerful API interfaces to meet business requirements. Open interfaces for the versatile applicability of data and information represent a central key position here. The more complex an interface must be designed, the more important an open and defined structure is. This is then documented with an appropriate description language.
Open API provides developers with a modern and powerful API description language for their projects. Based on Swagger’s open source tools, which are already very successfully established on the market, the new Open-API project was founded in 2015 under the leadership of the Linux Foundation from the Open-API Initiative. This initiative currently has 26 active members, many of whom are big players. Here, renowned companies such as Microsoft, Google, SAP, Paypal, Adobe, Smartbear or MuleSoft can be found. This ensures a comprehensive compatibility and structure of the services provided and published.
Version 3 has been available since 2017 for project planning and implementation of powerful APIs. One of the biggest advantages of Open-API is the comprehensive language support for Java, JScript, .Net, Ruby, Scala or Gitlab. These are all based on the formats of JSON or YAML 1.2 and thus provide very high compatibility. Further innovations can be found in the finally adapted and extended support of the JSON schema. In addition, innovations and restructurings have been introduced in the areas of security and hosts. The reuse of components was solved in a particularly convenient way. HTTP headers, requests, responses, parameters, callbacks, links, object schemes and examples can now be stored in a separate area.
The core elements of Open API
The requirements should already be clearly defined during the planning of an API. Here it is particularly important to deal with the core elements of functionality and later documentation. Every user of an API must be able to access the information of the used parameters, endpoints, return values and safety factors. This is the only way to ensure optimum and efficient use of the interface. There are various groups of core data in the Open API, which we will discuss in more detail below.
Documentation
In order to be able to map the individual components of the API clearly, external documents are usually also made available to explain the API functions, parameters, endpoints or details of the website such as terms of use etc. In the area Docs corresponding references to these documents and schemata can be inserted. The following example shows the format to be used:
A short description of the document contents is inserted after the parameter description:. The url: parameter also provides the link to the document resource.
Details
Within the section Details all basic information about the API is provided. This information is also valid API-wide. This section contains important parameters that should be entered. The following source code excerpt describes the individual values in the required format:
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.api-portal.io/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging.api-portal.io/v2
description: Optional server description, e.g. Internal staging server for testingThe first section info: describes the function of the API in short words. The parameter title: names a freely selectable title for the API, the second parameter description: names the core function of this API and may also contain external links to a reference source.
The version: section speaks for itself and maps the currently used API version. This information is especially valuable for different revisions of an API.
The servers: section now lists the active host of this API. In the url: parameter, each base path used is listed individually and in detail. With the parameter description: follows a short description of the path.
Security
The Security section describes all authentication methods used and permitted in the API. For each entry, there are various parameters that refer to the use of the schema. The following source code excerpt shows an example of the correct use:
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
BearerAuth:
type: http
scheme: bearer
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OpenID:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read: Grants read access
write: Grants write access
admin: Grants access to admin operationsIn addition to Basic and Bearer-Auth, other schemas can also be specified. With OAuth2, several details are assigned to the URLs and scopes. The access level can then be specifically named here. As soon as the security rule is entered in the root, it is valid for the entire API. Here is a possible scenario in which the security schema OAuth2 only allows read and write access:
security:
- ApiKeyAuth: []
- OAuth2:
- read
- writeFurthermore, a distinction is also made between the possible authentication methods with regard to the individual resource operations such as reading and writing. In the following example, the OAuth2 method with admin rights is defined specifically for read access to invoice information:
paths:
/billing_info:
get:
summary: Gets the account billing info
security:
- OAuth2: [admin] # Use OAuth with a different scope
responses:
'200':
description: OKResources
Typically, an API uses a wide variety of resources such as files, forms, or other information. To access this data, the HTTP protocol also defines various request and access methods. This signals to a browser, for example, how to deal with the request. Basically there are 4 standard request methods which can be applied to resources. In the following we present these together with a simple example parameterization:
GET - With this HTTP method a resource can be read. Please note that a GET method must not change any inventory data on the server. To find and read a specific entry using the identifier, use the following query method: GET /user/{userID}
POST - The POST method is usually used to create a new resource whose URI is not yet known to the system. This is the default method for adding a new resource: POST /user 2.
PUT - Use this method to edit or change an existing and known resource. This method is mainly used for updating data: PUT /user 2
DELETE - To delete a known and existing resource, use the DELETE method with the identifier. Please note the resource rights, if the method call with the user rights can be executed at all: DELETE /user/{userID}
The corresponding method parameters are specified in detail for each individual resource. The following source code shows an example of the search for a user data record. Status code 200 for the successful query and codes 400 and 404 for error messages are defined as return values:
paths:
/user/{userId}:
get:
summary: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
description: The ID of the user to return.
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: A user object.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
example: 4
name:
type: string
example: Jessica Smith
'400':
description: The specified user ID is invalid (not a number).
'404':
description: A user with the specified ID was not found.
default:
description: Unexpected errorTypes
In the type definitions of the API all used business objects are described in detail with ID and the properties together with value ranges. Descriptive categories are also used to better classify the object. In the following example, you create a reusable object in the component container with all relevant properties, data types and scopes:
components:
schemas:
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: stringErrors
One or more status messages should also be defined for each API request. This applies in particular to errors that occur. The more precisely you assign error codes to each API call, the easier it will be to handle the interface. Under the parameter responses you define all error codes that can be returned. Use the parameter description: to document the type of error message as a reference to the source.
Advantages and disadvantages of Open API
With the new version 3 of the Open API many bugs have been fixed and long overdue new features have been added. The large community and the broad application by the Swagger tools will inspire a fast standardization. The participation of many big players and the lack of a vendor lock will also provide a powerful boost. Many well-known frameworks now also rely on broad Open API support. Above all, the broad restructuring in user administration and in the header area makes handling much easier. A further clear advantage are the now reusable objects via their own section.
But where there is light, there is usually also shade to be found. Currently, only a few tools and development environments are specifically designed for Open API. Also the reuse of code snippets is not yet available and there are certain incompatibilities between the versions. However, these shortcomings will certainly be eliminated in the foreseeable future.
Conclusion
The markup language Open API has many advantages and therefore similarities with RAML. However, due to the relatively good selection of code generators and the many tools in the ecosystem, many project managers will prefer Open API. If you attach great importance to extensive language support, this is the right place for you. In the medium term, Open API will probably become the new standard in API documentation, which the already large community will certainly welcome.