So you are thinking to write API for your company and you stumble upon RAML. Here today I will be giving you a introduction to RAML basics for more detailed info you can check out http://raml.org/about/about-raml, I will be using the latest verison of RAML i.e. 1.0 in my design below.
-
What is RAML?
RAML stands for RESTful API Modeling Language. It’s a way of describing practically-RESTful APIs in a way that’s highly readable by both humans and computers. It is vendor-neutral, open-specification language built on YAML 1.2 and JSON for describing RESTful APIs.
“practically RESTful” because, today in the real world, very few APIs today actually obey all constraints of REST. RAML isn’t strict for now, it focuses on cleanly describing resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many, though perhaps not all, RESTful constraints. Check out these constraints to be Completely RESTful at Representational state transfer at Wiki.
-
Creating .raml for your API
The entity for which I will be creating the API is customer. This API will define basic CRUD operations for Customer entity and few query operations. Below is the list of resources we will be defining for our API
- GET /api/v1/customer
- POST /api/v1/customer
- GET /api/v1/customer/{id}
- PUT /api/v1/customer/{id}
- DELETE /api/v1/customer/{id}
- GET /api/v1/customer/name/{name}
- GET /api/v1/customer?name={name}&role={role}
And let’s define our API to be stateless, using HTTP Basic authentication, and to be delivered encrypted over HTTPS. Finally, let’s choose JSON for our data transport format (XML is also supported).
-
Setting the Root of RAML
At root level all the setting that we do get applied to entire API. Let’s start by creating a simple text file and name it cutomerAPI.raml. It is suggested to prefix it .raml as it will be used later by tools that we will be using to generate actual implementaion of API’s. You can name the file anything you like.
on line 5 the use of braces { } around the word “version“. This is how we tell RAML that “version” refers to a property and is to be expanded. Therefore the actual baseUri will be: http://company.domain.com/api/{version}
[Note: the version property is optional and need not be a part of the baseUri.]
-
Setting Security of API
Security is also defined at the root level of the .raml file. So let’s add our HTTP basic security scheme definition:
-
Setting Data Types of API
For our entity customer let’s define the Data type, i.e. the properties of our customer
The ‘?’ character following a property name declares that the property is not required.
-
Resources Definition
our top level resource is going to be customer
-
URI Parameters
Expand the list of resources, building from our top-level resource
Here, the braces { } around property names define URI parameters. They represent placeholders in each URI and do not reference root-level RAML file properties as we saw above in the baseUri declaration. The added lines represent the resources /customer/{id} and /customer/name/{name}.
-
Methods
The next step is to define the HTTP methods that apply to each resource
-
Query Parameters
Now we’ll define a way to query the customer collection using query parameters. Note that query parameters are defined using the same syntax that we used above for data types:
-
Responses for resources
Now that we have defined all of the resources for our API, including URI parameters, HTTP methods, and query parameters, it is time to define the expected responses and status codes. Response formats are typically defined in terms of data types and examples.
This example shows that by performing a GET request on the resource /customer/{id}, we should get back the matching Customer in the form of a JSON object and an HTTP status code of 200.
Here is how we would define the GET request on the /customer resource:
use of square brackets [] appended to the Customer type, this demonstrates how we would define a response body containing an array of Customer objects, with the example being an array of JSON objects.
-
Request Body
Next we will define the request bodies that correspond to each POST and PUT request. Let’s begin with creating a new Customer object
-
Status Codes
Note in the above example that when creating a new object, we return an HTTP status of 201. The PUT operation for updating an object will return an HTTP status of 200, utilizing the same request and response bodies as the POST operation.
In addition to the expected responses and status codes that we return when a request is successful, we can define the kind of response and status code to expect when an error occurs.
Let’s see how we would define the expected response for the GET request on the/customer/{id} resource when no resource is found with the given id.
-
Includes in RAML
As we go on with the design our API will start gettting repetitive and we will be writing and copying many things again and again, to over come this issue RAML provides a machenism to do include in your API by taking out examples and schema and security etc to seprate file and then using include to put them in place. We can refactor our API definition using includes, making it more concise and less likely to contain the types of errors that result from the “copy/paste/fix everywhere” methodology.
For example, we can put the data type for a Cutomer object in the file types /Customer.raml and the type for an Error object in types /Error.raml. Then our types section would look like this:
-
Tools used to design
I am using Anypoint platform by Mulesoft to do editing and development of my RAML. Here is the link for that https://anypoint.mulesoft.com/
you can get the detail of RAML here Customer API
In the second part continuing this blog I will be writing the implimentation of using the customer RAML to create real API using Mulesoft Anypoint Studio along with the more tools and refrences.
I hope i was able to give a basic idea about RAML and it’s usage, we have just touched the surface of great ability of RAML to define API I will strongly suggest to read the RAML.org website to get detail info about RAML 1.0