Introduction
In this article, we will discuss the RESTful API Modeling Language (RAML). It is an open-specification language which is built on top of YAML, wherein JSON is used for describing RESTful API resources.
We will also cover the RAML 1.0 basic syntax & files/fragments structure with examples. Also, discuss fragments that are components used to compartmentalize the RAML code logically. Its achieved with the use of “includes” keyword. This simplifies the API file maintenance.
Here, we demonstrate API design with the examples shown below.
API Designer
It is one of the web-based tools– which is part of anypoint platform and helps in designing the API & gives the overall picture of an API with mock services.
Designing Root RAML
Defining the API(.raml file)
Assume that we want to handle the restful requests for candidates entity. Thus, we will define the resources for basic CRUD (create, retrieve, update & delete) operations. If required, we can also define input params as shown below:
Basically, an API is created with stateless HTTP connection. If required, it can also be converted as HTTPS.
Either JSON or XML format is supported for transferring data. In this example, we have used JSON format.
Root Level Settings
Root level settings of RAML file is applied to the entire API which may include title, version, protocol, base URI etc.,
{ } curly braces in baseUri indicates a property which will be replaced with version v1.
Security
Authentication and Authorization can also be implemented using HTTP basic security scheme at the root level in RAML or the same can be achieved through policies that are supported by anypoint platform.
Data Types
All the basic data types are supported in RAML such as integer, string, date etc. Data validations and regex patterns are also supported.
The ‘?’ character in the above example is the syntax to mark a property as optional (i.e., not a required one).
Resources
After defining the root level settings, common things for the entire API, we can start defining the resources which are the restful requests for the mock API. Here, candidates are the top-level resource; all the other resources will be defined under this root resource & those are considered as child resources.
/candidates:
URI Parameters
URI parameter is one of the input parameters using which we can pass input data to rest api. URI parameters can be defined in two ways–either along with the endpoint with { } or using “uriParameters” at the node level.
In the above code snippet, the braces { } around property name indicate this as a URI parameter. The above resources with URI params form the URI (part of URL) such as “/candidates/{id}” & “/candidates/name/{name}”.
Methods
HTTP request methods can be used to define CRUD operations as follows:
Query Parameters
Another possible way of passing an input data to the resources is defining query parameters using the keyword “queryParameters”.
Responses
We have designed all the resources for an API with URI params, Query params & http methods. Now, we can define the responses of each method and status codes. We have used JSON structure for defining the responses as shown below,
Let us start with the simple GET operation on /candidates/{id}:
This example shows how to get data based on the resource call “/candidates/{id}“ for GET request. As a result, matching candidate will be displayed in JSON format with the status code of 200.
Here is how we would define the GET request on the /candidates resource:
The square brackets [] are used in the candidates type as a syntax. This demonstrates how to define an array of candidates objects (i.e., an array of JSON objects).
Request Body
In the above example, we used GET request. Now, we can discuss how to use POST and PUT requests. As the name indicates, GET is for fetching data, PUT is used to update an existing data, and POST is used to create fresh data.
Request Body is the way of passing input data to HTTP methods PUT/POST. The below example demonstrates the syntax to define request bodies to each POST/PUT end points of candidates resource.
Status Codes
There are different status codes available to indicate the success or error responses. Here are a few samples:
- 200 series indicate success responses
- HTTP status of 200 means OK
- HTTP status of 201 means CREATED
- HTTP status of 201 means ACCEPTED
- 400 series indicate client error responses
- HTTP status of 400 means BAD REQUEST
- HTTP status of 401 means UNAUTHORIZED
- HTTP status of 404 means RESOURCE NOT FOUND
- 500 series indicate server error responses
- HTTP status of 500 means INTERNAL SERVER ERROR
- HTTP status of 502 means BAD GATEWAY
When the searched record not available for the GET request on the /candidates/{id} resource , response is:
RAML With JSON Schema
candidates object type can be defined at the root level of the .raml file using JSON as follows,
Here is how we can use the candidates object type in the GET /candidates/{id} resource definition as follows:
Refactoring with Includes
To avoid repetitive code , improve code reusability and to logically compartmentalize the code, we can write the code into different raml files. This allows us to externalize the code. It can be referred in root raml using includes.
For example, we can define candidates object in the file “candidates.raml“ under types folder and Error object in “Error.raml“ under types folder. Then, our types section would look like this:
If we use JSON schema instead, it can be defined like this:
Completing the API
After externalizing all the data types and examples to their files, we can refactor our API using the include facility.
API fragments
An API fragment is a RAML document that has a version and an identifier but is not in itself a complete RAML specification. An API fragment is one of the following types defined by RAML.org:
- Trait
- Resource Type
- Library
- Type
- User Documentation
- Example
- Annotation Type
- Security Scheme
