RAML

RESTful API Modeling

Language
Arjun Kumar Bachuwar
bachuarjun@gmail.com

Agenda

Introduction on Web APIs

RESTful API
Write RAML for your REST API
Complete RAML showcase
JSON schemas

Web APIs
Web APIs Externalizes the enterprise

Web APIs
Online population statistics

Web APIs
1 medium not enough to reach all

Web APIs
Way to reach all

An Ideal Web API should

have

Good Documentation
Stability and Consistency
Flexibility
Security
Ease of Adoption

RESTful API
Representational State Transfer
A flavor of web API
RESTful systems typically, communicate over the Hypertext Transfer
Protocol with the same HTTP verbs (GET, POST, PUT, DELETE, etc.)
used by web browsers to retrieve web pages and send data to
remote servers.
RESTful is Clientserver, Stateless, Cacheable, Layered system,
Uniform interface, Identification of resources, Self-descriptive
messages

Example
RESTful API HTTP methods
Resource

Collection
URI, such as
http://exampl
e.com/songs/

GET

List songs
from songs
collection.

PUT

POST

Replace/Upd
atethe song
in song
collection.

Createa new
song in the
song
collection

DELETE

Deletethe
song from
songs
collection.

RAML-What is it?
RESTful API Modeling Language (RAML) is a
simple and concise way of describing
practically-RESTful APIs.
It encourages reuse, enables discovery and
pattern-sharing
RAML is built on broadly-used standards
such as YAML and JSON and is a nonproprietary, vendor-neutral open spec
Built on broadly used standards such as
YAML and JSON

Why to use
Its enables well-defined human
readable contract
This can understood by Developers,
Partners, API-consumers
Flexible

Sample RAML

RESTful API

RAML Header

Representational State Transfer

REST is a flavor of web API
SOAP is another flavor

RESTful API

Basic info of
your API

Representational State Transfer

REST is a flavor of web API
SOAP is another flavor

RESTful API
Representational State Transfer
REST is a flavor of web API
SOAP is another flavor
Common
Parameters/Hea
ders

RESTful API
Representational State Transfer
Resource
REST is a flavor of web API
SOAP is another flavor

RESTful API
Representational State Transfer
Zero or More
REST is a flavor of web APItraits can be
specified for
SOAP is another flavor resource

RESTful API
Specify Action
Using HTTP
Verb

Representational State Transfer

REST is a flavor of web API
SOAP is another flavor

RESTful API
Representational State Transfer
Specifying query
REST is a flavor of web API
parameters
SOAP is another flavor

RESTful API
Responses for
Representational State Transfer
the particular
action, You can
REST is a flavor of web API
have multiple
SOAP is another flavor responses

Request with body

Specifying
request structure
for the
particular action
using JSON
schemas

!include
Schema file can
be specified as
separate file and
you can include
it using !include

!include

Part of raml can

be written in
sub-raml file and
you can include
it

!include

tags.example.json

songs.raml

tags.schema.json

resourceTypes

resourceTypes

Sample JSON schema

Type as object

Sample JSON schema

Object type will
have properties
and each
property can be
another json
type

Sample JSON schema

Type can be
object, string,
number, array,
boolean

JSON schema Arrays

Type should be
array
You can specify
each item
structure with
items

More Info

For RAML refer http://raml.org/

For JSON Schemas
http://json-schema.org/

Thank You