Introduction to REST APIs and OpenAPI

REST APIs are used to interconnect systems, over a network, using HTTP.

An increasing number of services provide an HTTP based REST API as an interface to other network elements. REST APIs are prevalent in web-based development. For example there exist REST APIs from YouTube, Google Maps and so on. Many of these REST APIs may have utility within the scope of SS7/IMS/VoLTE services.

Historically, applications running on Rhino TAS, including Sentinel VoLTE, have had to support REST APIs by using the HTTP Resource Adaptor, and manually constructing the appropriate HTTP messages, which is time-consuming and prone to errors.

Alternatively, it is possible to write a dedicated Resource Adaptor (RA) that presents Rhino applications with a clean Java interface to a REST API. Such development is a lot of work, which must be repeated for each REST API that is to be supported. This can result in a proliferation of RAs which are very similar, if each RA only supports one API.

OpenAPI is a standard for describing REST APIs in a language-independent form. The OpenAPI Specification is maintained by the OpenAPI Initiative, an industry body with members from companies that develop and use REST APIs, including Google, Microsoft and many others. OpenAPI was previously known as Swagger.

An OpenAPI document is a text file (YAML or JSON) that describes the operations that a REST API supports. This document contains detailed information about parameters and types required by the API, and the HTTP requests and responses used by each operation.

This document is the authoritative description of an API, which can be used by developers and automated tools to build services around the API.

The OpenAPI YAML excerpt below shows how a typical REST operation may be specified. This operation uses a HTTP GET request, with the path /pet/{petId}, where {petId} is an integer, e.g. /pet/1234. The response will contain JSON or XML content that follows the referenced schema (in another part of the document, not shown here).

An interactive example can be seen at https://editor.swagger.io/. This is a web application that lets users edit their API and see the changes immediately in the generated documentation.

The OpenAPI Specification has emerged as the industry standard for describing REST APIs, and this has enabled many tools for generating code and other resources. The problem of "how can my application talk to or implement this REST API" has largely been solved — tools such as openapi-generator can generate client and server code for many languages and frameworks, so getting up and running with a new REST API is a simpler task.

A standard, unambiguous way to describe REST APIs is useful as a form of documentation for the humans that use the API. But the real benefit is the automation from tooling that understands these documents. Tools that support OpenAPI can use these documents to generate clients, servers, tests or documentation for the API.

The OpenAPI document is usually sufficient to completely generate a client implementation. For example, most client generators will turn the above operation into a getPetById(long) method that applications can call, without knowing about the underlying HTTP requests and responses. This is very powerful and means that REST APIs can be adopted easily when they are specified in OpenAPI.

The server implementation of an API cannot be completely generated as there will be application logic needed to query or update databases or other components, but the skeleton of a server implementation can be generated, with stubs for the developer to fill in the application logic.

The open source openapi-generator tool is commonly used for generating code from OpenAPI documents. It supports many programming languages and frameworks, and can be extended to generate custom code.