The document discusses RAML (RESTful API Modeling Language) which is an open specification language for designing and documenting RESTful APIs. It allows for designing APIs in a single file using a human-readable format. RAML supports modularity through reusable patterns like traits, resource types, and schemas to reduce duplication. It also emphasizes design-first and iterative development. The presentation encourages using RAML to avoid common API problems by designing before coding and getting feedback to improve designs.

1. Crafting Web APIs that Others Love
An Introduction to RAML 1.0

2. All contents © MuleSoft Inc.
About Me
• API Addict
• Technology = Love
• Developer & Open Source
Contributor
• Traveler or such
• Community Product Manager
@ MuleSoft
@ChristianVogel_

3. All contents © MuleSoft Inc.
Expectations vs Reality
APIs are not designed with their
consumers in mind

4. All contents © MuleSoft Inc.
Imagine you’re building a city using Legos.
“I want my city to have a fire department, a
police department, and a park.”

5. All contents © MuleSoft Inc.

6. All contents © MuleSoft Inc.

7. All contents © MuleSoft Inc.
You didn’t have any specs…

8. All contents © MuleSoft Inc.
Spec Driven Development – Design before Code
Design Code

9. All contents © MuleSoft Inc.
Spec Driven Development – Be Agile
Design Code

10. All contents © MuleSoft Inc.
The goal is that by utilizing agile user testing,
carefully designing, and prototyping your API in
an iterative state, that most design related
issues have already been discovered and
resolved. Allowing you to develop fearlessly.
- Mike Stowe

11. All contents © MuleSoft Inc.
Some of Today’s Top Spec Formats

12. All contents © MuleSoft Inc.
Let me introduce you to RAML

13. All contents © MuleSoft Inc.
Design and
Document your
APIs in a single file
An open spec language
designed to be human
readable and to encompass
the entire API lifecycle
Core
What is RAML?

14. All contents © MuleSoft Inc.
What does RAML look like?
#%RAML
0.8
title:
World
Music
API
baseUri:
http://example.api.com/{version}
version:
v1
/playlist:
#
resource
get:
#
HTTP
method
responses:
200:
#
HTTP
response
code
body:
application/json:
#
HTTP
response
media
type
example:
|
{
“playlistID”
:
1,
“playlistName”
:
“My
Awesome
Playlist”,
“genre”
:
“top40”,
“songs”
:
40
}

15. All contents © MuleSoft Inc.
Indeed, the ratio of time spent reading versus
writing is well over 10 to 1. We are constantly
reading old code as part of the effort to write
new code. ...[Therefore,] making it easy to read
makes it easier to write.
- Robert C. Martin, Clean Code: A Handbook of
Agile Software Craftsmanship

16. All contents © MuleSoft Inc. 16

17. All contents © MuleSoft Inc.
The good old duplication problem.

18. All contents © MuleSoft Inc.
Mobile Order API
my-api.com/products?page=1&limit=50
// get, post
my-api.com/products/{product_id}
// get
my-api.com/orders/{order_id}
// get
my-api.com/orders?page=1&limit=50
// get, post
my-api.com/basket?page=1&limit=50
// get, post
my-api.com/orders/{backetitem_id}
// get
• every collection has at least a get and post, as
well as two query parameters: page and limit
• every item in a collection has at least a get
method

19. All contents © MuleSoft Inc.

20. All contents © MuleSoft Inc.
Duplication is the primary enemy of a well-
designed system.
- Robert C. Martin, The Robert C. Martin Clean
Code Collection

21. All contents © MuleSoft Inc.
Reusability &
Pattern
Core
How does RAML help?
An open spec language
designed to be human
readable and to encompass
the entire API lifecycle
Create reusable
pattern-oriented
assets shareable
across multiple
APIs
traits
resource
types
security
schemes
schemas

22. All contents © MuleSoft Inc.
Hoe does modularization look like?
• You can use design patterns
• You can reuse code (traits, resource types)
resourceTypes:
collection:
description:
Collection
of
available
<<resourcePathName>>.
get:
description:
Get
a
list
of
<<resourcePathName>>.
responses:
200:
body:
application/json:
example:
|
<<exampleCollection>>

23. All contents © MuleSoft Inc.
Hoe does modularization look like?
/orders:
type:
collection:
exampleCollection:
|
{
"orders":
[
{
"id":
"order1"
}
]
}

24. All contents © MuleSoft Inc.
Data Modeling
Reusability &
Pattern
Core
RAML’s Evolution to v1.0
An open spec language
designed to be human
readable and to encompass
the entire API lifecycle
traits
resource
types
security
schemes
schemas
Libraries
Overlays &
Extensions
Typed Fragments
Increases RAMLs
core strengths
around reusability
and separation of
concerns; and
introduces a
unified,
streamlined, and
powerful way to
model data
Annotations

25. All contents © MuleSoft Inc.
Avoid duplication by
creating standardized
reusable patterns /
fragments
Design-first in a human-
readable format to
validate, collect
feedback, and iteratively
improve your design

26. Enough theory! Let’s see how to
actually do this stuff.

27. All contents © MuleSoft Inc.
come and visit us on
raml.org
@ramlapi

28. All contents © MuleSoft Inc.
and the most important
CONTRIBUTE / SEND FEEDBACK
https://github.com/raml-org/raml-spec

29. All contents © MuleSoft Inc.