3. RAML – Architecture
Architecture of somethings defines that what is the structure of a
system, what are its elements and other stuff. RAMLs architecture is
quite simple and understandable which makes it one of the top
vendors for designing APIs.
We’ll know more of its architectural components in further slides.
4. Root definition
Say you are creating webservices for Bla-Bla Mobile store. So first step is to create
the Root of your RAML file for that write following code:
#%RAML 0.8
title: Bla-Bla Mobile store API
baseUri: http://api.blablamobilestore.com/{version}
version: v1
Now what does the above code mean:
•#%RAML 0.8 – Defines the version of RAML specs
•Title - describes title of the API. It is mendatory property.
•baseUri – It is the URL where your API is hosted. All the resources for the
API can be accessed from this URL.
•Version – It depicts the version of API.
5. Resources & URI Parameters
Well resources are the services that a web API provides. In our example of Bla Bla mobile
store, a user can create an account and there are several orders he has done in past. So we
can declare the resources as follows:
/user:
/orders:
/profile:
Now in above code, user is a resource and in user resource further two resources orders
and profile are there. If we are to open orders for the user then we can just access through
following URL:
http://{baseUri}/user/orders
We can also add URI variables:
/user:
/orders:
/{id}:
The above code means for user there are orders and we can then fetch a specific order by
adding ID in path then. That’s how creation of resources works.
6. The Methods
The methods here are the HTTP methods. We can declare all the methods that a
resource can support. Some HTTP methods are -
GET - Retrieve the information defined in the request URI.
PUT - Replace the addressed collection. At the object-level, create or update it.
POST - Create a new entry in the collection. This method is generally not used at
the object-level.
Example:
/user:
/orders:
get:
post:
This code means the resource allows to get all the orders for user by using GET
HTTP method and also allow to create a new order by POST method.
7. Query Parameters
Query parameters are used to send various key-value pairs inside URI after ‘?’ symbol.
Developers mostly use query parameters to be able perform actions like filtering a collection.
Query parameters are a great way to accomplish this. Example –
/user:
/orders:
get:
queryParameters:
type:
quantity:
post:
In above code, the resource /orders can have two query parameters ‘type’ and ‘quantity’
which can be used to filter the results of the GET request for this resource.