OpenAPI

Definition of OpenAPI

The OpenAPI specification defines a standard, programming language-agnostic interface to RESTful APIs over HTTP(S) which allows humans and computers to discover and understand service capabilities without access to a service’s source code or documentation. OpenAPI is used

• By personas, that is developers, testers, operations support, API product managers, and others throughout the whole API lifecycle and
• By tools such as documentation, code generation to generate servers & clients in various languages, testing tools, API catalogues and browsers, API gateways, microgateways and other.

APIs are described in a so-called OpenAPI document containing all features required to actually access the API, such as:

• The URL of the server
• Paths to the APIs
• Which operations are supported (e.g., GET, PUT, POST, DELETE)
• Format of requests and responses (including HTTP status codes)
• The security schema required to access the API: basic HTTP authentication, JSON Web Tokens (JWT), OAuth2 or OpenID Connect.

The OpenAPI Document itself is a single JSON object which may be serialized either in JSON or YAML format (see the diagrams below for its overall structure and an example). OpenAPI allows for any type of request or response payload which can be specified according to RFC 6838 such as:

• application/json
• application/xml
• application/x-www-form-urlencoded
• multipart/form-data
• text/plain; charset=utf-8
• text/html
• application/pdf
• image/png

JSON is the most prevalent payload type due to the wide ecosystem support (tooling, documentation, best practices, tutorials). Additionally, OpenAPI allows the use of (a subset of) the JSON Schema specification to declare the syntax of requests and responses (e.g., which fields are mandatory or optional, data types of the fields etc.).

The following diagram contains a fairly simple example. More elaborate examples can be found on GitHub.

Technology Evaluation

OpenAPI started out as open source specification for designing REST APIs in 2010 as “Swagger”. In 2015, Swagger (2.0) was donated to the Linux Foundation, renamed to OpenAPI, and is now being maintained by the OpenAPI Initiative. It is a very comprehensive and rich standard for (syntactically) describing APIs albeit limited to RESTful APIs over HTTP(S). It can describe most of the possible REST APIs (e.g., including callbacks), but a few types of REST APIs (very intricate combinations of request/responses and schemas) cannot be described. Based on the absent precipitation of this in the web this does not seem to be a practical hindrance, though.

Limitations

• OpenAPI is limited to HTTP(S) as (application) protocol and, hence, cannot describe APIs based on any other protocol such as WebSockets, MQTT, or CoAP.
• The restriction to RESTful APIs (with GET, PUT, POST, and DELETE operations) means that it cannot describe HTTP/SOAP Web Services (which are typically described in WSDL) and other, non-RESTful services and APIs at all.

Market - Current Adoption

OpenAPI is the de facto largest industry standard for specifying RESTful APIs with a 70-80% adoption rate . Alternatives are RAML4 (RESTful API Modeling Language), GraphQL, API Blueprint, WADL (web application description language), Slate, gRPC and minor others.

It is supported by all major tools found in the full API lifecycle, see GitHub for examples.

Software AG has been supporting OpenAPI in the webMethods integration and API management products since Swagger 2.0. Full OpenAPI support in Software AG’s API Gateway product, for instance, allows code-less implementation of design-first, contract- or test-driven API development.

Market - Outlook

OpenAPI will still increase in significance and will become the single most important generic REST API description standard in the mid-term. This is directly driven by the “Tsunami” of IaaS/PaaS/SaaS and cloud applications which are all being accessed thru appropriate APIs.

For certain narrower domains (e.g., querying and updating many data sources at once or interfacing with native graph databases), other richer standards might become more attractive, for instance:

• (Open) Cypher — for querying graph databases
• GraphQL — also containing an implementation in form of a query engine
• gRPC – a performance-optimized way of specifying remote procedure call (RPC)-type of APIs originally invented (and heavily used internally) by Google

This, however, will be the exception rather than the rule.