The document discusses modularizing APIs using RAML fragments. It introduces different fragment types like data types, libraries, resource types and traits that can be used to break up large RAML specifications. Examples are provided on how to create fragments in API Designer and reference them in the main RAML file to organize the API definition into reusable modules.

1. Oct 23, 2020
Monterrey MuleSoft Meetup Group
Use of DataType and Library Fragments with API
Designer

2. 2
● Introductions
● Design your API with API Designer
● Create Fragments In RAML 1.0
● Modularizing APIs and Reusing Patterns in API’s
● Q/A
● What’s next
Agenda

3. 3
●About the organizer:
Introductions
A SHOW OF HANDS:
Who is new to this Meetup?
Veyra Gutiérrez Martínez
in/veyra-celina-532bb88
• Studies in Computer Science. Started working
with Mulesoft about a 3 years ago. My experience
in Integrations development drove me to enter to
this MuleSoft world, that I found awesome.
• Experience in different industries as.
• CMT
• Manufacturing
• Electric and gas
• Mulesoft fundamentals trainer

4. subtitle
Design your API with API
Designer

5. 5
● API & Integration Methodology.
MuleSoft’s AnyPoint Platform
API
• Design an API: Designing an API first before
actually building is often referred to as spec
driven development, in this development
process your application is built in two phases:
the design phase and the development phase

6. Design
● API Designer – it is web-based tool to design API’s REST interfaces or specifications as per
the requirement. While creating the interface it will validate the interface for any syntax error
and highlight the same. It also show the tab to validate the interface where it show the mock
interface
6

7. Mocking
● Mock Service – it is again one of the feature in Design Center through which we can quickly
validate the API specification. This only provide the Mock API without any actual
implementation and developer can validate request and response of the API
7

8. APIs
● Let's talk about API First………..
● What is API ?
8
An Application Programming Interface (API) provides the information for
how to communicate with a software component and define functionalities
independent of implementations.
Operations
(What to call?)
Inputs
(What to send with call?)
Outputs
(What you get from a call?)
Data Types
(What to expect receive and send?)
API
• The term API is often used to refer any part
of a RESTful web service
• The web service specification
• The web service interface implementing the
API
• The web service implementation itself
• A proxy
• Some benefits are:
• Provides Standard interface for
communication
• They are Reusable and Easy to use
• Provides a layer of security
- Hides the specifics of the systems talking to
each other
- Client is never fully exposed to the server
- Server is never fully exposed to your Client.
• APIs make it easy to efficiently share data
and processes
Web Service
API Specification
API Implementation

9. REST APIs
● Let's talk about REST APIs………..
● What is REST?
9
REpresentational State Transfer (REST) is a software architectural style
that defines a set of constraints to be used for creating Web services.
Those web services that follow this architecture are known as RESTful
Web services
Http Methods
o Http Verbs
Resource
o Entity that can be identified, named,
addressed, handled, or performed
Response
o Http code
Content Type
o Format Json, XML, HTML, etc
API
• REST APIs are distinguished by their strong
reliance on the HTTP application protocol. That is,
they use the HTTP response codes and methods for a
specific and widely recognized function. And it allows
us through the URI, the structuring of the available
resources.
• REST Development Advantages:
• Separation between the client and the server
• Visibility, reliability and scalability
• The REST API is always independent of the
type of platform or languages
{REST}
Json

10. Libraries and DataTypes Fragments
Create Fragments In RAML 1.0

11. 11
One of the great things about RAML is modularization.
This gives the ability to separate concerns within an
API specification.
One feature that illustrates this concept quite well is
“Typed Fragments”.
There are two types of typed fragments that get
confused often, namely “Libraries” and “DataTypes”.
Fragments
Library Fragment DataType Fragment
It can hold MULTIPLE types. Libraries are
referred to using the uses: statement and a dot
notation to refer to a type inside that library
It can only hold a SINGLE type. DataTypes are
referred to using the !include tag as value of a
type
#%RAML 1.0 <fragment-type>

12. How to create the RAML fragments
● Login in to Anypoint platform -> Go to design Center
● Click on Create new-> Create fragment
● Provide the fragment name
● Provide the type of fragment

13. DataType Fragment
● Taken from object-oriented programming
languages like Java, data types allow the user to
define objects and reuse them at any level in a
RAML file.
○ You can define types that inherit from other types.
○ You can define multiple properties each of which is
declared as a built-in type like string or number.
● Types are split into four families: external, object,
array, and scalar.
● You can define a facets (You specialize types
based on characteristics of facet values.
Examples: minLength, maxLength)
● In a RAML file, we can define simple and complex
data types.
13
#%RAML 1.0 DataType

14. Library Fragment
● Libraries are usually defined in an external file,
however, also can be defined inline.
● Can hold any number and combination of data
types, security schemes, resource
types, traits, and annotations.
● Libraries are imported via the top-
level uses statement
● A library is referenced by concatenating
the library name, a dot (.), and the name of the
element (e.g. data type, resource type, trait,
etc) e.g. type: library.typeInsideLibrary
14
#%RAML 1.0 Library
In RAML, it's possible to organize APIs in a more
readable way by using of libraries

15. subtitle
Modularizing APIs and Reusing
Patterns in API’s

16. Divide, reuse and conquer
● Avoid to design one huge API file with everything
on it, divide instead.
● Create reusable file fragments which can be
used later across your organization.
● Conquer the Spec Driven Development driven,
using best practices to develop and maintain
large software programs, by breaking them up
into smaller parts.
16
APIs

17. 17
How you can break your RAML API
definition into modules by making use
of typed fragments?.
○ Use of include key word to modularize a
complex property value in a RAML definition
by placing the property value in an external
file
○ Rather than placing all the types, resource
types or traits in their own
respective include files, you can also use
special types of includes known as typed
fragments to break each of these constructs
into multiple include files, specifying a
different file for each type, resource
type or trait.
Break your RAML
Fragment
Identifier
Description
DataType A data type declaration where the type node may be used
NamedExample A declaration of the examples facet, whose key is a name of
an example and whose value describes the example
ResourceType A single resource type declaration. 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
Trait A single trait declaration. Traits is like function and is used to
define common attributes for HTTP method (GET, PUT,
POST, PATCH, DELETE).
SecurityScheme A definition of a security scheme. A security scheme is used
to secure data access, identify requests, and determine
access level and data visibility
Library A RAML library. A library is used to modularize any number
and combination of data types, security schemes, resource
types, traits, and annotations
Overlay An overlay file. An overlay is used to extend non-behavioral
aspects of an API, such as descriptions, usage directions,
and user documentation items
Extension An extension file. An extension is used to extend or override
behavioral aspects of the API

18. Example

19. Example
● Given the entities types Foo and Bar, define basic CRUD operations and a couple of
query operations. Here are the resources that we will define for our API:
• GET /api/v1/foos
• POST /api/v1/foos
• GET /api/v1/foos/{fooId}
• PUT /api/v1/foos/{fooId}
• DELETE /api/v1/foos/{fooId}
• GET /api/v1/foos/name/{name}
• GET /api/v1/foos?name={name}&ownerName={ownerName}
• GET /api/v1/bars
• POST /api/v1/bars
• GET /api/v1/bars/{barId}
• PUT /api/v1/bars/{barId}
• DELETE /api/v1/bars/{barId}
• GET /api/v1/bars/fooId/{fooId}

20. Example
● Let’s the modularization begin...
● Where do I begin?
20
• Security.- Safety first, Let’s define a what type of
authentication mechanism will use our API.
#%RAML 1.0 SecurityScheme
1. Login in to Anypoint platform -> Go to design Center
2. Click on Create new-> Create fragment
3. Provide the fragment name: basicAuth_sample
4. Provide the type of fragment: Security Scheme
• Authentication mechanisms
 Basic Authentication
 Basic Auhtentication Client ID enforcement
 OAuth 2.0
 Custom token

21. Example
● Security check!!
● What’s next?
21
• DataTypes.- Next, we'll define the data types that
our API will use: Foo, Bar and Error.
#%RAML 1.0 DataType
1. Login in to Anypoint platform -> Go to design Center
2. Click on Create new-> Create fragment
3. Provide the fragment name: Foo
4. Provide the type of fragment: Data Type
1. Click on the ‘+’ icon and select “New File”
2. Provide the type of fragment: Data Type
3. Provide the fragment name: Bar; Error; Foo

22. Example
● Data Types Done!!
● What’s next?
22
• Library.- Next, we'll define the library or libraries
that our API will use: For data types, security
schemes, traits, resources types, etc.
#%RAML 1.0 Library
1. Login in to Anypoint platform -> Go to design Center
2. Click on Create new-> Create fragment
3. Provide the fragment name: dataTypes
4. Provide the type of fragment: Library
1. Click on the ‘+’ icon and select “New File”
2. Provide the type of fragment: Library
3. Provide the fragment name: dataTypes

23. Example
● That’s it?
● This is the end?
23
• Find the patterns and organize.- As we read
through the list of resources in our API, we begin to
see some patterns emerge. When we compare the
RAML definitions of the /foos and /bars resources,
including the HTTP methods used, we can see
several redundancies among the various properties
of each, and we again see patterns begin to emerge.
Wherever there is a pattern in either a resource or
method definition, there is an opportunity to use a
RAML fragment like a resource type, trait, example,
etc .

24. Q&A

25. Time to earn a pass to take free training course!
25
First Chance!!
Which are the four families in which
the DataType fragments split into?
¿Cuáles son las 4 familias en las
que se dividen los fragmentos
DataType?
Second Chance!!
Which is the key word used to
import Libraries and where should
be located?
¿Cuál es la palabra clave usada
para importer librerías y dónde
debe colocarse?
Third and Last
Chance!!
Name other 3 typed fragments
besides DataType and Library?
¿Nombre otros 3 tipos de
fragmentos además de Tipo de
datos y Biblioteca?

26. 26
● Share:
○ Next Meetup: TBD
○ Stay tune: https://meetups.mulesoft.com/monterrey/
● Feedback:
○ Don’t forget to fill out the survey feedback
○ Nominate yourself for the next meetup speaker and suggest a topic as well
What’s next?

27. Thank you

28. References
● https://mulesy.com/create-fragments-in-raml/
● https://mulesy.com/include-fragments-in-raml/
● https://mulesy.com/usage-of-library-fragment-in-raml/
● https://mulesy.com/basic-authentication-simple/
● https://www.baeldung.com/raml-restful-api-modeling-language-tutorial
● https://www.baeldung.com/simple-raml-with-resource-types-and-traits
● https://www.baeldung.com/modular-raml-includes-overlays-libraries-extensions
● https://medium.com/raml-api/raml-101-libraries-and-datatypes-fragments-1889b2e82c27
● https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#typed-
fragments
● https://dzone.com/articles/overview-on-raml-10
● https://dzone.com/articles/understanding-resourcetypes-and-traits-with-
raml#:~:text=3.0%20What%20Is%20Traits%3F,filterable%2C%20searchable%2C%20or%20p
ageable.