REST API Design

REST is merely an architectural model that does not specify the concrete implementation. To begin, you implement the following four steps:

1. Translate the application logic into the REST schema. This step requires a certain effort, but it saves half the battle. The extra effort pays off when you need to introduce external developers or new employees to the API logic, which also is often a key acceptance factor, especially for open APIs with a widespread developer community. A structured design process helps with the remaining steps [4] [5].
2. Design the interface model. The model determines what data is handled by the interface and what state the application assumes after each step. The relations between the roles involved in the process emerge here and appear as links later.
3. Define standards for the identifiers (e.g., links or media types) to the extent possible. Countless registered identifiers are already available [6]-[8]. An API will integrate in a far better way if it behaves as expected or in a known way. To match the identifiers closely, you then select the media types, often with the need to iterate through steps 2 and 3 multiple times until the results work out.
4. Document your own interpretation. As a result, you then ideally have an application profile that consists of a registered standard profile with minor adjustments. Only in this step do you get around to implementing the API.

OData

REST works especially well in the case of Internet applications with large numbers of users and million-fold parallel access, which explains why the major tech providers, especially, are increasingly relying on REST. In the field of data formats, the OASIS Open Data Protocol (OData) Technical Committee [9] endeavors to achieve standardization. Many major vendors support the initiative, including Red Hat, Microsoft, IBM, and SAP.

OData is a relatively comprehensive protocol and requires some training. The REST model is based on HTTP, the Atom Publishing Protocol [10], and JSON [11]; it consistently uses URIs to address resources. The deliberately varied use cases include relational databases, filesystems, and content management systems, as well as traditional websites.

In February 2017, the ISO Joint Technical Committee accepted the OASIS OData Standard for Open Data Exchange (ISO/IEC 20802-1:2016 [12] and 20801-2:2016 [13]). Against this background, OData is more of an industrial policy program and interesting in the context of large corporations or authorities.

OpenAPI

The Open API Initiative [14] focuses on vendor-neutral API format descriptions [15] on the basis of the Swagger specification [16]. The description language is designed to enable the development of APIs that both humans and machines can understand, independent of the programming language. The specification is available under the Apache 2.0 license; its supporters include Google, PayPal, Red Hat, and Microsoft. The many supporting tools [17], such as the YAML Swagger Editor shown in Figure 1, prove particularly useful.

Figure 1: The YAML Swagger Editor enables the design of an API directly in the web editor; the example shows the Uber API.

The Swagger Petstore (Figure 2) [18] is another highlight; a sample server demonstrates the specification and allows experiments. The OpenAPI specification is documented very clearly, which significantly shortens the learning curve and makes it suitable even for small projects.

Figure 2: Experimentation allowed – the Swagger Petstore shows a sample API.