The ins and outs of RAML

1. May 19, 2023 4:00 PM IST
Hyderabad MuleSoft Meetup
Group Present’s # 29
The ins and outs of RAML

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

3. A recording of this meetup will be uploaded to events page within 72 hours.
Questions can be submitted/asked at any time in the Chat/Questions & Answers Tab.
Make it more Interactive!!!
Share us the feedback! Rate this meetup session by filling feedback form at the end of the day.
We Love Feedbacks !!
Housekeeping
3

4. Organizer’s

5. About the Speaker :
Introduction
Neha Modi,
Senior Consultant, NJC labs
5
● Working as Senior Consultant @ NJC Labs.
● 7+ years of IT experience, specializing in integration space.
● Certified MuleSoft Developer & Architect.
● Mulesoft Mentor.
● Experience in Mule, Oracle SOA 12c, OSB, AWS, TIBCO BW.

6. ● What is an API
● What is RAML
● API Specification vs API Fragments
● RAML design best practices
● Different Fragment Type and their Usage (Datatypes, Library, Security Schema etc)
● Demo
● Q&A
Agenda
6

7. All about RAML

8. ● API stands for Application Programming Interface.
● API is way of communicating or interacting between two or more interfaces.
What is API
8

9. ● RESTful API Modeling Language is a YAML based language for describing RESTful APIs.
● It is an API design language that allows developers to take advantage of the full API Design
Lifecycle, meaning that they can visually design their APIs, test them, and get user
feedback without ever having to write a single line of code.
What is RAML
9

10. An API fragment is a portion of an API specification, which is why understanding it starts at
the API specification level.
API Specification vs API Fragment
10

11. ● Data Type
● Library
● Example
● Security Schemes
● Resource Types
● Traits
Fragment we will discuss
11

12. RAML file names are in lowercase, alphanumeric characters using kebab case (i.e. hyphen
separated).
For example:
● acme-banking-api.xml
● account-example.raml
● acme-bank-doc.raml
RAML Best Practices
12

13. ● API Titles
○ The title of the API should be a short, plain text label for the API.
■ title: ACME Banking API
● API description
○ The description of the API should be a short, plain text label for the API.
■ description: API for ACME Banking Service
● Version
○ Each API should have a corresponding alphanumeric version number.
■ version: 1.0.0
● Protocols
○ The optional protocols node specifies the protocols that an API supports. If the protocols
node is not explicitly specified, the protocol in the baseUri node is used.
■ protocols: [HTTP, HTTPS]
RAML Header
13

14. ● Specifying the OPTIONAL mediaType node sets the default media type for responses and
requests that have a body.
■ mediaType : application/json
RAML Media Type
14

15. ● RAML DataTypes provide a concise and powerful way of describing the information utilized
within the API.
● DataTypes add rules for validating data against a type declaration.
● The types node within the API RAML is used to refer to external datatype.
Example:
DataType
15

16. ● ResourceType is basically a template that is used to define the descriptions, methods, and parameters
that can be used by multiple resources without writing the duplicate code or repeating code.
● ResourceTypes should be created as separate files and included at the start of the API RAML file.
Example(collection.raml ):
ResourceType
16

17. ● Traits is like function and is used to define common attributes for HTTP method ( PUT, POST,
PATCH, DELETE, etc) such as whether or not they are filterable, searchable, or pageable,etc.
● Traits should be created as separate files and included at the start of the API RAML file.
Examples:
Traits
17

18. ● Each authentication pattern supported by the API must be expressed as an element of the security
Schemes node value.
● The security schemes should be created under a separate folder and included within the API RAML
file. Example:
Security Schemes
18

19. ● RAML libraries are used to combine any collection of data type declarations, resource type
declarations, trait declarations, and security scheme declarations into modular,
externalized, reusable groups. While libraries are intended to define common declarations
in external documents, which are then included where needed, libraries can also be
defined inline.
Libraries
19

20. Keywords & its Usage
20
Sl.no Component Keyword in library Keywords in main
root raml
Sample
1 datatype types types types:
orderRq: !include /datatype/order.raml
2 resourceTypes resourceTypes resourceTypes resourceTypes:
collection: !include
/resourcetype/collctn.raml
3 traits traits is traits:
clientId: !include traits/clientId.raml
is: [clientId]
4 securityScheme
s
securitySchemes securedBy securitySchemes:
basic: !include /securityscheme/basic.raml
securedBy: [basic]
5 library NA uses uses:
myLib: /library/library.raml
6 examples - !include example: !include /examples/createOrder.xml
7 documentation usage documentation usage:
docs: !include

21. Demo

22. References
● https://blogs.mulesoft.com/learn-apis/api-led-connectivity/what-is-an-api-fragment/
● https://www.mulesoft.com/resources/api/design-apis-easily-with-RAML
● https://docs.mulesoft.com/api-manager/2.x/prepare-raml-task
22

23. Q&A

24. Take a stand !
24
●Nominate yourself for the next meetup speaker
https://sfdc.co/hyd-meetup-nomination

25. 25
● Share:
○ Tweet using the hashtag #MuleSoftMeetups #MuleSoftCommunity
○ Join Hyderabad Group: https://meetups.mulesoft.com/hyderabad
● 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?

26. Thank You