RESTful API Modeling Language (RAML)

The most detailed and complete documentation of an API is particularly important in terms of usability and maintenance. In terms of content, all important parameters, business objects, error codes and additional information must be described exactly and ideally also with short examples. The core elements shown below should therefore be present in every API description and presented as detailed as possible. We describe the different areas with a fictional example of an airline in which different actions such as bookings, cancellations or requests for information are to be made.

For the most detailed description of the API components, corresponding documents can be named in the section docs. A user manual can also be integrated here in the form of links and includes. For this, the two parameters documentation: and title: are available to describe a reference link. It is also a multiple naming of links and descriptions possible. The following source text snippet shows an example:

Basic information about the full API is noted in the Details section. For this purpose, various parameters such as info:, title: or servers: are available. In the following source text excerpt you can see an example of our fictitious airline:

The title: parameter should describe the basic functionality of the API. The version specification in the version: parameter is of interest to revision control. The baseUri: parameter specifies the path to the API, which may include a versioning level. In description: you give more information about the API. Under mediaType: you list the format language used for the API.

In this section, all safety information is noted. Usually the authentication methods used in the API are listed here. The security level and other parameters are defined via various specifications. The following source text section describes the authentication settings for our fictitious company:

The first parameter securedBy: defines the authentication method to be used, which is valid as root over the whole API. This is followed by one or more definitions with a set of parameters such as type:, displayName:, describedBy: and queryParameter:. With these details the used authorization procedure is described in detail. This is followed by information on the access token access_token: and the possible response codes responses:.

To define the access to the different resources via the API, different access methods are used in the HTTP protocol. As a rule, the four most common method calls come into question here. These signal to the browser how to handle a request and how to use the parameters it carries. The following list briefly introduces the four method calls:

GET - The GET method can be used, for example, to read a resource without changing the inventory data. For our fictitious airline, this call would correspond to a query about a particular flight.

POST - The POST method is intended to create a new resource. The resource to be generated must not yet exist in the system. In our example, this method call corresponds to the creation of a new customer booking for a flight.

PUT - You can use this method to change or complement a resource that already exists in the system. A change to the flight data, such as the departure time, in an existing booking would be a corresponding example.

DELETE - If a resource is no longer needed in the system, you can use this method call to delete it. This would be the case if a customer wants to delete a booking record that has already been saved.

In the API, the corresponding parameters are listed in detail for each method call. Using our airline as an example, a visitor searches our website for suitable flights using the search parameters (queryParameters). In the following source text you will find an excerpt of the exemplary definition of the GET method:

An essential part of the API definition is the detailed representation of the business objects used with all required parameters. Here we also find the object properties like departure_airport:, destination_airport: or price: One of these object types for the flight search (FlightSearchType) we will briefly introduce in the following source code excerpt:

Another important section in the API definition are the communication status messages. These should be listed in as much detail as possible in order to be able to carry out a possible troubleshooting or user message effectively. An error message is returned in JSON format, as the following source code excerpt shows:

Compared to other markup languages such as Open API, RAML offers a simple and convenient way to integrate recurring source code and schemas. There is also an active community that provides excellent support and code snippets. With professional tools like the Atom Plugin API Workbench or the Mule Studio a fast and comfortable project planning is possible. A disadvantage here are the few available tutorials that could make it easier for a newcomer to get started. Another problem is the lack of downward compatibility of the different versions as well as the relatively small number of languages compared to other description languages.

If you basically need fast and clean designs for RESTful API’s, the RAML description language is currently a clear advantage. Especially with regard to agile API-First projects, the documentation should be kept as simple but transparent as possible. Due to the flexible reusability of objects and code fragments, RAML can clearly score against the competition. With RAML, the integration of XML schemata is completed in seconds. In particular, the API Workbench is very easy and intuitive to use. Nevertheless, it should be noted that due to new developments and advancing standards, the Open API markup language is gaining considerable popularity and will probably be defined as a new standard in the foreseeable future.