Basics of Designing an API using RAML

1. RAML API Designing Basics
Part 1

2. • Introduction
• RAML API Schema
• Root
• Resources
• Methods
• URI Parameters
• Query Parameters
• Responses

3. • 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.
Introduction

4. • 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.
Introduction

5. 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

6. • 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}
Root

7. 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:

8. 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:

9. 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

10. 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:

11. • 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
Query
Parameters
• To make a GET call, the URI looks like
http://api.EmpolyeeDet.com/v1/ employees/ Thomas Anderson?
employeeId =E001

12. 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>

13. Example
Root
Resource
URI Parameter
Method
Query Parameter
Response
Note The Pipe

14. Thank You