using raml 1.0 like a pro

Using RAML 1.0 Like a Pro

Using RAML 1.0 Like a ProMay 2016


Mike RoseChief ArchitectAvenueCode

End-to-End Project

Delivery

Collaborative

Development

Shared Project

Ownership

Mobile

Dev Ops

Agile Coaching


End-to-End Project

Delivery

Collaborative

Development

Shared Project

Ownership

Mobile

Dev Ops

Agile Coaching

Customers


End-to-End Project

Delivery

Collaborative

Development

Shared Project

Ownership

Mobile

Dev Ops

Agile Coaching

Partners


Agenda

•API Challenges•RAML explained•RAML benefits•RAML features•RAML 1.0 Applied•Q&A

5


API ChallengesUsing 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


API Challenges

• High degree of abstraction• Difficult to capture requirements• Common vocabulary is largely absent


8


API Challenges

• Without language

- Miscommunication

- Lack of shared expectations

- Little opportunity for collaboration


9


RAML ExplainedUsing 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


RAML Explained

• RAML enables- Design

• Design matters

What is RAML?

12


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


RAML Explained

• RAML helps you manage change• Change management choices

- Refactoring RAML- Refactoring code

What is RAML?

14


RAML BenefitsUsing RAML 1.0 Like a Pro


RAML benefits

• Reusable componentsHow does RAML help?

16


RAML benefits

• Refactoring supportHow does RAML help?

17


RAML benefits

• Team developmentHow does RAML help?

18


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


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


RAML FeaturesUsing 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


RAML Features

• The bad stuff- JSON Schema- YAML !include- Uneven application of data types

RAML 0.8 was a good start

23


RAML Features

• RAML data types- Simple specification- Applied consistently- Syntactic sugar- Easily reused

Improvements in RAML 1.0

24


RAML Features

• Annotations- Custom metadata- Leverages RAML data types


25


RAML Features

• Modular RAML- Components

• Fragments• Libraries

- Definitions• Overlays• Extensions


26


Applying RAML 1.0Using 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


RAML 1.0 Example

• Basic user data- Name- Email address- List of friends

• Queryable• CRUD

Simple profile API

29


Applying RAML 1.0

• Challenges- Managing multiple APIs- Keeping DRY- Team environment

Basic development tasks

30


RAML 1.0 Example

• RAML solution- Libraries

• Types• ResourceTypes• Traits


31


RAML 1.0 Example


32


Applying RAML 1.0

• Challenges- Complexity- Separation of concerns

API Security

33


RAML 1.0 Example

• RAML solution- SecurityScheme

• Choose a security provider type• Specify client authentication requirements

API Security

34


RAML 1.0 Example

API Security

35


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


Applying RAML 1.0


• Define new hypermedia types• Extend type definitions with links

HATEOAS

37


Applying RAML 1.0

HATEOAS

38


Applying RAML 1.0

• Challenges- Versioning- Deprecation- Retirement

API Lifecycle Management

39


Applying RAML 1.0


• Deprecation data types• Deprecation annotations

- Extensions• Refactor out common API definitions• Override common API for each version


40


Applying RAML 1.0


41


Q & AUsing 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

mailto:[email protected]