API Designing with RAML

1. Designing modern APIs
using MuleSoft Anypoint
Platform : Almost Instantly!!
Birmingham MuleSoft Meetup Group
09/17/21

2. Organizer
2
About Organizer:
• 15+ years of Technical Experience.
• 4+ years of Experience in MuleSoft Architecture.
• Certified MuleSoft API Designer.
• MuleSoft Meetup Speaker.
• Birmingham Mule Meetup Leader.
Mohammad Sakif
Integration Architect

3. Speaker
3
Sonali Mehta
Senior MuleSoft Architect
About Speaker:
• 15+ years of Technical Experience.
• 4+ years of Experience in MuleSoft Architecture.
• Certified MuleSoft API Designer.
• MuleSoft Mentor
• MuleSoft Meetup Speaker.

4. • Both the speaker and host are organizing this meet up in individual capacity, only.
We are not representing our companies here.
• This presentation is strictly for learning purpose only. Organizer/Presenter do not hold any responsibility
that same solution will work for your business requirements also.
• This presentation is not meant for any promotional activities.
Safe Harbor Statement
4

5. CHEERS..!!
We have prizes to give away!
3 Winners a special prize is ready
5
A SHOW OF HANDS:
New Members With Us.!!

6. 6
● Introducing MuleSoft AnyPoint Platform and API LifeCycle
● How to use API Designer to create API Specifications?
● Introducing RAML
● Defining resources , methods , parameters and responses using RAML
● Modularizing an API
● Simulating an API
Agenda

7. 7
● Engaging users in design phase
● Sharing an API
● Publishing an API in Anypoint Exchange
● Example APIs
● Further Reading
Agenda

8. Introduction to MuleSoft Anypoint
Platform and API LifeCycle

9. 9
MuleSoft Anypoint Platform

10. 10
Design Once, Deploy Anywhere

11. API-First Design Approach

12. 12
API Lifecycle Management

13. 13
Anypoint Design Center

14. 14
Steps for designing API using RAML

15. Introduction to RAML
(RESTful API Modelling Language)

16. 16
RAML : RESTful API Modeling Language
• RAML is a human- and machine-readable language for the definition
of a RESTful application programming interface (API).
• RAML is designed to improve the specification of the API by
providing a format that the API provider and API consumers can use
as a mutual contract.
• RAML is based on broadly used standards such as YAML and JSON.
• RAML files can be used to auto generate documentations, mocked
endpoints , interfaces for API implementations etc.
• RAML uses a human readable data serialization format where data
structure hierarchy is specified by indentation.

17. 17
RAML : Resources, Methods and Parameters
• A resource is a conceptual mapping of an entity or set of entities.
• Resources are the objects identified by web service url that you want
to act upon using HTTP method used for the request
• All resources begin with a slash
• Any methods and parameters nested under a resource belong to
and act upon that resource
• Nested resources are used for a subset of a resource to narrow it
• URI parameter which is a variable element, enclosed in curly
brackets ({}) inside a relative URI of a resource.

18. 18
RAML : Defining Response And Request
Details
• Responses must be a map of one or more HTTP status codes
• For each response , specify a possible return datatypes along with
description and examples
• Same as response details, for a request specify each request data
type along with description and example

19. 19
RAML : Examples
1. HelloWorld API
#%RAML 1.0
title: Hello world # required title
/helloworld: # optional resource
get: # HTTP method declaration
responses: # declare a response
200: # HTTP status code
body: # declare content of response
application/json: # media type
type: | # structural definition of a response (schema or type)
{
"title": "Hello world Response",
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
example: | # example of how a response looks
{
"message": "Hello world"
}

20. 20
Example - American Flights API

21. 21
RAML : Simulating an API
• You can mock an API to test it before it is implemented. It is useful to
get early feedback from stackholders
• Use the API console and mocking service to run a live simulation in
API designer
• While performing mocking service it returns sample API responses
written in API definition
• Mocking service is available for outside stockholders through
shareable links
• API console is available in API Designer and API Portal in Anypoint
Exchange so users and designers can test it

22. 22
RAML : Modularizing an API
• RAML introduces the innovative concept of resource types and traits
for characterizing and reusing patterns of resources and associated
methods. Using resource types and traits minimizes the
repetition in a RESTful API design and promotes consistency
within and across APIs.
• Instead of putting all the code in one RAML file, you can modularize
it and compose it in reusable fragments
Datatypes Traits
Examples Documentation
Resource Types Annotation
Security Schemes Libraries

23. 23
RAML : Modularizing an API
• API fragments can be stored in different files and folders within a
project
• Fragments can be stored as a separate project in API design center
• Fragments can be stored in a separate RAML fragment in Anypoint
Exchange

24. 24
#%RAML 1.0
title: Example API
version: v1
mediaType: application/json
types:
Users: !include types/users.raml
User: !include types/user.raml
resourceTypes:
collection:
get:
responses:
200:
body:

25. traits:
secured:
description: Some requests require authentication
queryParameters:
<<methodName>>: # e.g. get:
description: A <<methodName>>-token pair is required # e.g. A get-token pair...
example: <<methodName>>=h8duh3uhhu38 # e.g. get=h8duh3uhhu38

26. #%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
oauth_2_0:
description: |
Dropbox supports OAuth 2.0 for authenticating all API requests.
type: OAuth 2.0
describedBy:
headers:
Authorization:
description: |
Used to send a valid OAuth 2 access token. Do not use
with the "access_token" query string parameter.
type: string
queryParameters:
access_token:
description: |
Used to send a valid OAuth 2 access token. Do not use with

27. 27
RAML : Engaging users in design phase
• To build a successful API, you should design it iteratively , getting
feedback from developers on usability and functionality along the
way
• To make API accessible, you need to provide ways to developers to
discover the API and play with it
• You can share an API with developers and make it discoverable
using Anypoint Exchange

28. 28
RAML : Publishing an API in Anypoint Exchange
• You can publish RAML API specification and API fragments to the
Anypoint Exchange from API designer
• API portals are automatically created for REST APIs added to
exchange
• An API console for consuming and testing APIs
• An automatically generated API endpoint that uses a mocking
service to allow the API to be tested without having to implement
it

29. 29
● HelloWorld API
● T-Shirt Ordering Service API
● American Flights API
● Banking Payment Process API
● RAML-Examples
Sample APIs : Demo

30. 30
● raml.org : https://raml.org/developers/raml-100-tutorial
● raml.org : https://raml.org/developers/raml-200-tutorial
● https://github.com/raml-org/raml-spec/blob/master/versions/raml-
10/raml-10.md
● RAML-Examples : https://github.com/raml-org/raml-examples
RAML : Further Reading

31. Get ready to WIN a Special Gift from MuleSoft Community
Quiz Time

32. You should not be a meetup leader.
In last 30 days you shouldn’t own any trivia quiz in any
meetup.
Important Instructions for the
attendees to play Trivia quiz

33. 1. Log in to www.kahoot.it via your mobile
phone
Click on “Play” on top right hand side of
the web page
Enter the game pin that is displayed on the
quiz master’s screen
Give your complete name as the nickname
You will be getting your questions on your
laptop screen with option.
For every questions you will get 20 sec to
answer.

34. 34
Share:
○ Tweet your pictures using the hashtag #BirminghamMuleSoftMeetup
○ Invite your network to join: https://meetups.mulesoft.com/birmingham/
Feedback:
○ Fill out the survey feedback and suggest topics for upcoming events
○ Contact MuleSoft at meetups@mulesoft.com for ways to improve the
program
What’s next?

35. Thank You