Spec-Driven API development using RAML
Modern day API's need to be specific, scale-able ,mutually exclusive & highly accessible with ease of integration. Its is like a atom/cell which can be interlaced in simpler manner to create a complex business eco-system
While developing a API below are the few of the things one needs to focus on -
- Core functionality - Heart of your API everything else becomes the outerlayer
- Resource & Method - Whom the API talk to and how
- API security - Most important factor in today's world.Dealing with who and what is accessible by whom
- Interface - Window how it can communicate with external word
- Modularity - How it can be Modeled into a micro-service which can be integrated with other similar service to create a bigger ecosystem.
- Resource Management - Resource to be remodeled for re-usability to scale the functionality (using !include functionality in RAML)
Above all are specification which one need to have if he/she is planning to build an API. Thus we need to have a standard specification which governs the basic law of API building. For SOAP you have Web Service Descriptive Language (WSDL) which tells what the API does, how to access those API, what are the endpoints and what security policy its support . But when it comes to REST API we don't have any spec or guidelines. This is where RAML specification comes into picture.
Restful API Modelling Language (RAML) is a specification used to create a restful API service. At present it is not a mandatory guideline but it good to have sort of guideline which ensures your API blueprint is as per the modern day spec. RAML is a machine-readable API design which can be easily understood my any one ( be he form business / developer background ). Below is a generic structure of a RAML API.
#%RAML 1.0
title: placeholder
version: 1.0.development
baseUri: http://jsonplaceholder.typicode.com
/users:
get:
description: Retrieve a list of all the users
responses:
200:
body:
application/json:
example: |
[{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
} }]
/userbyid:
get:
description: Get information about a particular user
queryParameters:
id:
description: Specify the id of the user you want to retrieve
type: integer
required: false
example: 3
responses:
200:
body:
application/json:
example: |
[{
"id": 3,
"name": "Clementine Bauch",
"username": "Samantha",
"email": "Nathan@yesenia.net",
"address": {
"street": "Douglas Extension",
"suite": "Suite 847",
"city": "McKenziehaven",
"zipcode": "59590-4157",
"geo": {
"lat": "-68.6102",
"lng": "-47.0653"
}
},
"phone": "1-463-123-4447",
"website": "ramiro.info",
"company": {
"name": "Romaguera-Jacobson",
"catchPhrase": "Face to face bifurcated interface",
"bs": "e-enable strategic applications"
} }]
As a mule ESB developer I can tell you that RAML has made the life of an API integrator specialist very much comfortable. Now if your Mule flow has an external/internal rest API to be consumed. You define a RAML spec for that API using a tool such Mulesoft Anypoint Design Center. Here you see the various spec that RAML support for a restful API.Once you build your RAML API using the spec,you create a zip package and import it into Anypoint studio using Mule API Kit to be integrated into the business flow.
Below is an image of simple RAML API created using MuleSoft Anypoint Design Center
Next image shows RAML API imported into Anypoint studio to be integrated within business flow
The RAML implementation makes sure that all dependency & inconsistency related to API building are taken care while creating the API even the security aspect is also covered thus ensuring that during time of integration the developer don't have to bother about those things and he can simply integrate the API into main business flow.
Useful Link :
