2. RAML API Designing Basics
• Introduction
• RAML API Schema
• Root
• Resources
• Methods
• URI Parameters
• Query Parameters
• Responses
3. Introduction
What is RAML ?
• RAML : RESTful API Modeling Language.
• Non-proprietary, vendor-neutral open spec.
• Aims to help current API ecosystem and solve immediate problems,
and then gently encourage ever-better API patterns.
Why RAML ?
• Makes it easy to manage the whole API lifecycle from design to
sharing.
• Concise - you only write what you need to define.
• Reusable.
• Machine readable API design that is actually human friendly.
4. API Schema
Root
• Some basic information about the API. i.e. title, baseUri, version etc.
Resources
• Decides how API can be used by consumers.
Methods
• To define what consumers can do with the resources.
URI Parameters
• To have dynamic resources, to act upon the more granular objects of
the resources.
Query Parameters
• To be passed to methods, to extend the functionality of the API.
Responses
• HTTP status codes, may include descriptions, examples or schemas
5. Root
• Contains Some basic information about the API. i.e. title, baseUri,
version etc.
• Everything entered in at the root (or top) of the spec applies to the rest
of the API.
• Chosen baseURI will be used with every call made, hence make sure to
keep it clean and concise.
Example :
• #%RAML 0.8
• title: Employee Details Management
• version: v1
• baseUri:
https://mocksvc.mulesoft.com/mocks/c2a7ecf4-edd3-
4023-8373-c3a2cf325dda/api/{version}
6. Resources
• Decides how API can be used by consumers.
• Resources always begin with a slash ( / ) in RAML.
• Any methods and parameters nested under these top level resources
belong to and act upon that resource.
• Nesting of resources is also possible.
Example :
• /employees:
• /department:
• /region:
7. Methods
• To define what consumers can do with the resources.
• Most common HTTP methods :
• 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.
• delete : Delete the information defined in the request URI.
• Each HTTP method can only be used once per resource.
• Lower case must be used for methods in RAML API definition.
Example :
• /employees:
• get:
• post:
• put:
delete:
8. URI Parameters
• To have dynamic resources, to act upon the more granular objects of
the resources.
• Used for nesting of resources.
• A URI parameter is denoted by surrounding curly brackets in RAML.
Example :
• /employees:
• /{employeeName}:
• With above, to make a request to this nested resource, the URI for the
employee, ‘Thomas Anderson’ would look like
– http://api.EmpolyeeDet.com/v1/ employees/ Thomas Anderson
9. Query Parameters
• To be passed to methods, to extend the functionality of the API.
• To make developers to be able to perform more powerful actions, like
filtering a collection based on passed parameters.
• Query parameters may also be something that the server requires to
process the API consumer's request, like an access token.
Example :
• / employees :
• /{employeeName}
• get:
• queryParameters:
• employeeId :
• put:
• queryParameters:
• access_token:
10. Continue…
• Each query parameter may have any number of optional attributes to
further define it.
• Example :
• / employees :
• /{employeeName}
• get:
• queryParameters:
• employeeId :
• displayName: Employee Id
• type: string
• description: Id of an employee
• example: E001
• required: false
11. Responses
• A map of one or more HTTP status codes.
• Each response may include descriptions, examples or schemas
• Note the pipe ( | ) after ‘example’ keyword, it’s to indicate what follows
is a string, if not put, it’ll give an error saying, ‘example must be a
string’.
Example :
• / employees :
• /{employeeName}:
• get:
• description: Retrieves details of a specific employee
• responses:
• 200:
• body:
• application/json:
• example: |
• {
• …<sample data>
• },
• "success": true,
• "status": 200
• }
14. • The main flow for a RAML-based API manages these functions:
• Exposes the API using HTTP or Jetty.
• Routes requests between the interface and the backend flows based on
the HTTP request.
• References exception strategies that produce HTTP-status-code responses.
Main Flow
15. Backend Flows
• APIkit generates a backend flow for each resource-action pairing in a
RAML. APIkit for SOAP generates a backend flow for each operation in a
WSDL. For example, the RAML interface receives the GET request for sales
of T-shirts. The backend flow accesses a database to look up sales data
and responds to the request.
17. Connection Details
United Airlines: RESTful web service
• URL: http://mu.mulesoft-training.com/essentials/united/flights
Delta Airlines: web service• URL:
• URL: http://mu.mulesoft-training.com/essentials/delta
American Airlines: MySQL database
• Server: mudb.mulesoft-training.com
• Port: 3306
• User: mule
• Password: mule
• Database: training
• American table: flights
Editor's Notes
/books:
/{bookTitle}
get:
queryParameters:
author:
displayName: Author
type: string
description: An author's full name
example: Mary Roach
required: false
publicationYear:
displayName: Pub Year
type: number
description: The year released for the first time in the US
example: 1984
required: false
rating:
displayName: Rating
type: number
description: Average rating (1-5) submitted by users
example: 3.14
required: false
isbn:
displayName: ISBN
type: string
minLength: 10
example: 0321736079?
put:
queryParameters:
access_token:
displayName: Access Token
type: string
description: Token giving you permission to make call
required: true
/books:
/{bookTitle}:
get:
description: Retrieve a specific book title
responses:
200:
body:
application/json:
example: |
{
"data": {
"id": "SbBGk",
"title": "Stiff: The Curious Lives of Human Cadavers",
"description": null,
"datetime": 1341533193,
"genre": "science",
"author": "Mary Roach",
"link": "http://e-bookmobile.com/books/Stiff",
},
"success": true,
"status": 200
}