Mule soft RAML API Designing

RAML API Designing Basics
• Introduction
• RAML API Schema
• Root
• Resources
• Methods
• URI Parameters
• Query Parameters
• Responses

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.

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

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}

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:

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:

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

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:
• access_token:

Continue…
• Each query parameter may have any number of optional attributes to
further define it.
• Example :
• / employees :
• /{employeeName}
• get:
• employeeId :
• displayName: Employee Id
• type: string
• description: Id of an employee
• example: E001
• required: false

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
• }

• 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

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.

Flights API
API
United
American
Delta
Front-end
UI
Mule ESB

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

Mule soft RAML API Designing

More Related Content

What's hot (18)

Similar to Mule soft RAML API Designing (20)

Recently uploaded (20)

Mule soft RAML API Designing

Editor's Notes