API Specification

1. April 04, 2024
Dublin MuleSoft Meetup Group
API Design using Anypoint Studio

2. #MuleSoftMeetups
Organizers
Kunal Gupta has over 9 years of dedicated work experience in Integration Development, Execution, and
Delivery.
Extensive involvement in diverse project implementations, placing a strong emphasis on API Management,
including Analysis, Design, Development, and Implementation.
Linkedin - Kunal Gupta | LinkedIn

3. Speaker
3
Afreen is a MuleSoft mentor and working as a Mulesoft Developer at Zurich Insurance.
She has great experience in Integration, development, execution and delivery using the
MuleSoft products and offerings. Afreen has completed the following certifications -
1. MCD Level 1
2. MCPA and MCIA
Linkedin - Afreen Fatma | LinkedIn

4. 4
AGENDA
• Introduction: Fundamentals of RAML
• API Specification vs API Fragment
• Different fragment types and their usage
1. Traits
2. Library
3. Data Type
4. Examples
5. Resource Type
6. Security Scheme
• Best Practices
• Demo

5. Fundamentals of RAML
5

6. Fundamentals of RAML
6
What is RAML ?
1. RAML stands for RESTful API Modeling Language.
2. It is a YAML based Language for describing RESTful APIs.
3. It provides a structured, clear format for describing an API.
4. It is designed to promote reuse, readability, and shared understanding among users.

7. Fundamentals of RAML
7
Why do we need RAML?
1. Clear documentation
2. Code Reusability
3. Collaboration
4. API Mocking

8. API Specification vs API Fragment
8
• An API fragment is a portion of an API specification, which is
why understanding it starts at the API specification level.
• An API specification consists of a plan of how your API should
look structurally.

9. API Fragment
9
API fragments are reusable component of RAML to make the
design and build of a reusable API even quicker and easier.
Another advantage of building an API spec out of reusable API
fragments is that consistency of definitions reduces the effort of
implementing APIs.

10. 10

11. Different types of API Fragment
11
Traits
• Mulesoft traits, serves as a powerful tool for enhancing integration
projects.
• A “trait” typically refers to a reusable configuration or behaviour that
you can apply to one or more elements within your mulesoft project.
• Traits are a way to define a set of common properties,
configurations, or behaviours that can be shared among different
components, such as connectors, flows, and error handlers.
• They enhance the reusability and maintainability of your integration
projects by allowing you to define common settings in a central
location and apply them consistently.

12. Different types of API Fragment
12
Library
• A library is a RAML fragment that contains reusable definitions and
can be included in other API specifications as well.
• Example: A library could contain dataTypes, traits, and
resourceTypes that are common across multiple APIs.
• Benefits: Libraries help in organizing and maintaining common
definitions in a central place.

13. Different types of API Fragment
13
DataTypes
• DataTypes in RAML fragment are way to define the structure of
data that is sent or received.
• Example: A datatype could define a ‘User’ object with properties
such as ‘name’, ‘email’ and ‘age’.
• Benefits: DataTypes ensure the consistency of data structure
across the API and can be reused across multiple APIs.

14. Different types of API Fragment
14
Examples
• Examples are a way to shoe a sample payload for a method in your
API.
• Example: An example of a ‘User’ datatype could show a sample
JSON object with ‘name’, ‘email’ and ‘age’.
• Benefits: Examples provide a way for developers to understand the
expected request or response structure.

15. Different types of API Fragment
15
Resource Type
• Resource types are reusable components that can be applied to
multiple resources.
• Example: A resource type could define a ‘collection’ of items with
‘get’, ‘post’, ‘put’, and ‘delete’ methods.
• Benefits: Resource Types allow for the reuse of common resource
behaviours and reduce the need for repeated specification.

16. Different types of API Fragment
16
Security Scheme
• Security schemes are defined ways to secure an API and can be
applied to multiple methods or resources.
• Example: A security scheme could define an OAuth 2.0 security
flow.
• Benefits: Security schemes ensure the consistency of API security
and can be reused across multiple APIs.

17. Best Practices
● Start with the API Consumer in mind
● Use Restful principles
● Utilize API Fragments
● Follow consistent naming conventions
● Use HTTP status codes appropriately
● Leverage API-led connectivity
● Version your APIs
● Secure your APIs
● Documentation
17

18. Reference
18
 Overview of API Fragments Design Strategies | MuleSoft Blog
 RAML 101: Libraries and DataTypes Fragments | by Jonathan
Stoikovitch | RAML by Example | Medium
 API Best Practices: How to Design and Manage APIs | MuleSoft
 API Fragments and Why They Matter – PlektonLabs
 Why API Specs Are the Backbone of Successful Development |
Ready, Set, Cloud! (readysetcloud.io)

19. Q & A Session

20. Thank you