The new RAML 1.0 specification provides new features and additional flexibilty that makes it easier to design and create great APIs. In this session we will review some best practices for RESTful APIs and show how to add these features to your own APIs using the RAML specification. We will also cover common design patterns and address FAQs such as how to use annotations and add metadata to APIs.

1. Using RAML 1.0 Like a Pro
Using RAML 1.0 Like a Pro
May 2016

2. Using RAML 1.0 Like a Pro
Mike Rose
Chief Architect
AvenueCode
End-to-End
Project
Delivery
Collaborativ
e
Developmen
t
Shared
Project
Ownership
Mobil
e
Dev Ops Agile Coaching

3. Using RAML 1.0 Like a Pro
End-to-End
Project
Delivery
Collaborativ
e
Developmen
t
Shared
Project
Ownership
Mobil
e
Dev Ops Agile Coaching
Customers

4. Using RAML 1.0 Like a Pro
End-to-End
Project
Delivery
Collaborativ
e
Developmen
t
Shared
Project
Ownership
Mobil
e
Dev Ops Agile Coaching
Partner
s

5. Using RAML 1.0 Like a Pro
Agenda
•API Challenges
•RAML explained
•RAML benefits
•RAML features
•RAML 1.0 Applied
•Q&A
5

6. Using RAML 1.0 Like a Pro
API Challenges
Using RAML 1.0 Like a Pro

7. Using RAML 1.0 Like a Pro
API Challenges
• REST is defined
by convention
- Some rules
- Few standards
- Many opinions
What is so hard about APIs?
7
RESTafarians debating the
merits of “shoe” vs. “gourd”
style APIs

8. Using RAML 1.0 Like a Pro
API Challenges
• High degree of abstraction
• Difficult to capture requirements
• Common vocabulary is largely absent
What is so hard about APIs?
8

9. Using RAML 1.0 Like a Pro
API Challenges
• Without
language
- Miscommunication
- Lack of shared
expectations
- Little opportunity
for collaboration
What is so hard about APIs?
9

10. Using RAML 1.0 Like a Pro
RAML Explained
Using RAML 1.0 Like a Pro

11. Using RAML 1.0 Like a Pro
RAML Explained
• Language for describing RESTful APIs
- Machine readable
- Human friendly
- Vocabulary for
• Functional aspects
• Non-functional aspects
• Descriptive aspects
What is RAML?
11

12. Using RAML 1.0 Like a Pro
RAML Explained
• RAML enables
- Design
• Design matters
What is RAML?
12

13. Using RAML 1.0 Like a Pro
RAML Explained
• Why design your APIs with RAML?
- You will not get it right the first time
- Done is short lived
- You need a strategy for dealing with change
What is RAML?
13

14. Using RAML 1.0 Like a Pro
RAML Explained
• RAML helps you manage change
• Change management choices
- Refactoring RAML
- Refactoring code
What is RAML?
14

15. Using RAML 1.0 Like a Pro
RAML Benefits
Using RAML 1.0 Like a Pro

16. Using RAML 1.0 Like a Pro
RAML benefits
• Reusable components
How does RAML help?
16

17. Using RAML 1.0 Like a Pro
RAML benefits
• Refactoring support
How does RAML help?
17

18. Using RAML 1.0 Like a Pro
RAML benefits
• Team development
How does RAML help?
18

19. Using RAML 1.0 Like a Pro
RAML benefits
• OAI / Swagger
- Strengths
• Generating documentation from existing
implementations
- Weaknesses
• Uneven / Inconsistent specification
• Lack of standardization / interoperability between tools
How does RAML compare to other tools?
19

20. Using RAML 1.0 Like a Pro
RAML benefits
• API Blueprint
- Strengths
• Creating API mocks from API Blueprint document
- Weaknesses
• Document format is only semi-structured
• Lacks tools for forward engineering
How does RAML compare to other tools?
20

21. Using RAML 1.0 Like a Pro
RAML Features
Using RAML 1.0 Like a Pro

22. Using RAML 1.0 Like a Pro
RAML Features
• The good stuff
- YAML
- Data modeling
- Patterns
- Tools
- Community
RAML 0.8 was a good start
22

23. Using RAML 1.0 Like a Pro
RAML Features
• The bad stuff
- JSON Schema
- YAML !include
- Uneven application of data types
RAML 0.8 was a good start
23

24. Using RAML 1.0 Like a Pro
RAML Features
• RAML data types
- Simple specification
- Applied consistently
- Syntactic sugar
- Easily reused
Improvements in RAML 1.0
24

25. Using RAML 1.0 Like a Pro
RAML Features
• Annotations
- Custom metadata
- Leverages RAML data types
Improvements in RAML 1.0
25

26. Using RAML 1.0 Like a Pro
RAML Features
• Modular RAML
- Components
• Fragments
• Libraries
- Definitions
• Overlays
• Extensions
Improvements in RAML 1.0
26

27. Using RAML 1.0 Like a Pro
Applying RAML 1.0
Using RAML 1.0 Like a Pro

28. Using RAML 1.0 Like a Pro
RAML 1.0 Example
• Design a simple service
• Progressively apply RAML 1.0 to
- Support the base API
- Add security constraints
- Implement HATEOAS principals
- Manage multiple versions
28

29. Using RAML 1.0 Like a Pro
RAML 1.0 Example
• Basic user data
- Name
- Email address
- List of friends
• Queryable
• CRUD
Simple profile API
29

30. Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges
- Managing multiple APIs
- Keeping DRY
- Team environment
Basic development tasks
30

31. Using RAML 1.0 Like a Pro
RAML 1.0 Example
• RAML solution
- Libraries
• Types
• ResourceTypes
• Traits
Basic development tasks
31

32. Using RAML 1.0 Like a Pro
RAML 1.0 Example
Basic development tasks
32

33. Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges
- Complexity
- Separation of concerns
API Security
33

34. Using RAML 1.0 Like a Pro
RAML 1.0 Example
• RAML solution
- SecurityScheme
• Choose a security provider type
• Specify client authentication requirements
API Security
34

35. Using RAML 1.0 Like a Pro
RAML 1.0 Example
API Security
35

36. Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges
- Collection query responses
• Array of links
• Links to first/prev/next/last pages
- Collection member responses
• URL aware
HATEOAS
36

37. Using RAML 1.0 Like a Pro
Applying RAML 1.0
• RAML solution
- Libraries
• Define new hypermedia types
• Extend type definitions with links
HATEOAS
37

38. Using RAML 1.0 Like a Pro
Applying RAML 1.0
HATEOAS
38

39. Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges
- Versioning
- Deprecation
- Retirement
API Lifecycle Management
39

40. Using RAML 1.0 Like a Pro
Applying RAML 1.0
• RAML solution
- Libraries
• Deprecation data types
• Deprecation annotations
- Extensions
• Refactor out common API definitions
• Override common API for each version
API Lifecycle Management
40

41. Using RAML 1.0 Like a Pro
Applying RAML 1.0
API Lifecycle Management
41

42. Using RAML 1.0 Like a Pro
Q & A
Using RAML 1.0 Like a Pro

43. Using RAML 1.0 Like a Pro
mrose@avenuecode.com
Skype: mutsys
GitHub: https://github.com/mrose-avenuecode
For more information, please visit
us
at booth G3 in the Expo
or online at
www.avenuecode.com
Project
Managemen
t
Busines
s
Analysis
Software
Developmen
t
Quality
Assuranc
e
Dev Ops
Product
Managemen
t