Upload
mulesoft
View
614
Download
0
Embed Size (px)
Citation preview
Using RAML 1.0 Like a Pro
Using RAML 1.0 Like a ProMay 2016
Using RAML 1.0 Like a Pro
Mike RoseChief ArchitectAvenueCode
End-to-End Project
Delivery
Collaborative
Development
Shared Project
Ownership
Mobile
Dev Ops
Agile Coaching
Using RAML 1.0 Like a Pro
End-to-End Project
Delivery
Collaborative
Development
Shared Project
Ownership
Mobile
Dev Ops
Agile Coaching
Customers
Using RAML 1.0 Like a Pro
End-to-End Project
Delivery
Collaborative
Development
Shared Project
Ownership
Mobile
Dev Ops
Agile Coaching
Partners
Using RAML 1.0 Like a Pro
Agenda
•API Challenges•RAML explained•RAML benefits•RAML features•RAML 1.0 Applied•Q&A
5
Using RAML 1.0 Like a Pro
API ChallengesUsing RAML 1.0 Like a Pro
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
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
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
Using RAML 1.0 Like a Pro
RAML ExplainedUsing RAML 1.0 Like a Pro
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
Using RAML 1.0 Like a Pro
RAML Explained
• RAML enables- Design
• Design matters
What is RAML?
12
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
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
Using RAML 1.0 Like a Pro
RAML BenefitsUsing RAML 1.0 Like a Pro
Using RAML 1.0 Like a Pro
RAML benefits
• Reusable componentsHow does RAML help?
16
Using RAML 1.0 Like a Pro
RAML benefits
• Refactoring supportHow does RAML help?
17
Using RAML 1.0 Like a Pro
RAML benefits
• Team developmentHow does RAML help?
18
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
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
Using RAML 1.0 Like a Pro
RAML FeaturesUsing RAML 1.0 Like a Pro
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
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
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
Using RAML 1.0 Like a Pro
RAML Features
• Annotations- Custom metadata- Leverages RAML data types
Improvements in RAML 1.0
25
Using RAML 1.0 Like a Pro
RAML Features
• Modular RAML- Components
• Fragments• Libraries
- Definitions• Overlays• Extensions
Improvements in RAML 1.0
26
Using RAML 1.0 Like a Pro
Applying RAML 1.0Using RAML 1.0 Like a Pro
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
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
Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges- Managing multiple APIs- Keeping DRY- Team environment
Basic development tasks
30
Using RAML 1.0 Like a Pro
RAML 1.0 Example
• RAML solution- Libraries
• Types• ResourceTypes• Traits
Basic development tasks
31
Using RAML 1.0 Like a Pro
RAML 1.0 Example
Basic development tasks
32
Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges- Complexity- Separation of concerns
API Security
33
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
Using RAML 1.0 Like a Pro
RAML 1.0 Example
API Security
35
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
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
Using RAML 1.0 Like a Pro
Applying RAML 1.0
HATEOAS
38
Using RAML 1.0 Like a Pro
Applying RAML 1.0
• Challenges- Versioning- Deprecation- Retirement
API Lifecycle Management
39
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
Using RAML 1.0 Like a Pro
Applying RAML 1.0
API Lifecycle Management
41
Using RAML 1.0 Like a Pro
Q & AUsing RAML 1.0 Like a Pro
Using RAML 1.0 Like a Pro
[email protected]: mutsysGitHub: https://github.com/mrose-avenuecode
For more information, please visit us
at booth G3 in the Expoor online at
www.avenuecode.comProject
Management
Business
Analysis
SoftwareDevelopme
nt
QualityAssuranc
eDev Ops
ProductManageme
nt