What are REST APIs?

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

API requests are represented as HTTP requests

The parameters of the API request are encoded using the HTTP method, query parameters, header and cookie values and the request body

API responses are represented as HTTP responses

The parameters of the API response are encoded using the response status, header and cookie values, and the response body

Rest APIs
Note Read Introduction to REST for a concise overview of REST (REpresentational State Transfer).

Why are REST APIs of interest?

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.

Note The Rhino REST API Framework provide tools to allow Rhino developers to easily add support for REST APIs in their applications.

What is OpenAPI?

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.

Note Developers describe their REST APIs with the OpenAPI Specification within the Rhino REST API Framework.

OpenAPI Examples

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 example OpenAPI operation
paths:
  '/pet/{petId}':
    get:
      tags:
        - pet
      summary: Find pet by ID
      description: Returns a single pet
      operationId: getPetById
      parameters:
        - name: petId
          in: path
          description: ID of pet to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

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.

What OpenAPI Enables

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.

Note The openapi-generator is the basis of the Rhino REST API Framework toolchain for generating Resource Adaptors for use in Rhino TAS - Telecom Application Server.
Previous page Next page