1. RAML is a new open specification for describing RESTful APIs using YAML that aims to be cleaner and more structured than existing documentation formats. 2. RAML uses a hierarchical structure and inheritance to define API resources, operations, parameters, headers and responses in a way that closely matches the structure of REST APIs. 3. The RAML specification is still evolving and there is growing tooling and libraries to support its use in designing, documenting, testing and implementing RESTful APIs.

1. RAML – APIs
Uri
Sarid
CTO,
Mule
Soft#RAML
@usarid
@MuleSoft

2. APIs:
The Cat's Meow

3. build on someone else's work… who's?
Ultimate Buzz for Creatively-lazy Developers
0
2
4
6
8
10
12
Source:
open APIs

4. yes, even Service-Oriented Architecture!
Modularity, Encapsulation, Specialization
q
eCommerce
q
products
q
shopping cart
q
checkout
q
billing
q
shipping
q
social
q
graph
q
posting
q
geolocation
q
city data
q
weather
q
attractions
q
businesses
q
collaboration
q
documents
q
notifications
q
forums
q
analytics
q
traffic
q
logs
q
NLP
q
sales
q
marketing
q
demographics
q
SFA
q
social

5. The API Economy Is Big and It's Now
1,000,000s
>13,000 Open APIs
Enterprise APIs

6. APIs and me

7. My Experience:
utility
back-office
software
consumer
portal

8. •
tells consumer devs what they'll get
The API Contract Is Critical
•
tells implementer devs what to deliver
•
ensures they'll meet in the end
•
enables parallel development

9. My Experience: Barnes & Noble /
Don't expose dirty laundry
users
products
orders
invoices


the layer cake
of APIs

10. At MuleSoft
connectivity

11. Packaged apps Custom apps Databases
The Traditional Enterprise
The traditional enterprise
sits comfortably behind the firewall

12. Welcome to the New Enterprise
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise

13. Connect backend
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise

14. Backend to SaaS
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise

15. Everything needs to connect
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise

16. The Anypoint Platform:
integration on-premises and cloud
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners
/ Suppliers
Mobility and Devices
Anypoint Platform
Business
Insight
Enterprise
Mgmt
Mule Studio
Anypoint
DataMapper
DataSense
Anypoint Connectors

17. The Anypoint Platform:
integration on-premises and cloud
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners
/ Suppliers
Mobility and Devices
Anypoint Platform
Business
Insight
Enterprise
Mgmt
Mule Studio
Anypoint
DataMapper
DataSense
Anypoint Connectors
100,000s
100s
1,000s
1,000,000s
1,000,000,000s

18. The Anypoint Platform for APIs
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners
/ Suppliers
Mobility and Devices
Anypoint Platform
Business
Insight
Enterprise
Mgmt
Studio
APIkit
Anypoint
DataMapper
DataSense
API Gateway
API Manager
Design/Dev Portal
Anypoint Connectors

19. An Opinionated Approach to
API Success

20. delight your users!
The Key to API Success?
how?
•
design for them
•
iterate quickly
•
model cleanly and consistently
•
engage

21. Codify
Req’s
Design API
Validate
Publish
Capture
Feedback
UI  UX
API  APX
Design For Your Users

22. ü
where consumers touch you
ü
your front door, your lobby, your façade
ü
how you want to be seen; your brand
ü
versioned more carefully than code
ü
better interfaces  better code
ü
an organizing principle; alignment forcing function
ü
the ultimate testing surface
Focus on the Interface: The Contract

23. 1. Describe APIs simply and clearly
2. Design APIs easily and soundly
3. Engage users in compelling ways
What kind of interface do we want?
NOT documentation
NOT annotations in implementation

24. •
nouns: resources, described by URI paths
•
verbs: HTTP methods
•
metadata: HTTP headers
•
responses: HTTP status codes
•
representations: appropriate media types in the body
•
use hypermedia – not necessarily, not yet
Practically-RESTful APIs
a few words
about REST…

25. What Do People Do Today?

26. WADL

27. Reverb Swagger

28. Mashery IOdocs

29. Google Discovery Docs

30. Apiary Blueprint

31. Verdict:
manifest
structure
capture
patterns
humanly
writeable
let's try
harder…

32. Start From Scratch?
Really???

33. •
well-known superset of JSON
•
optimized for human readability
•
great for hierarchies
•
cruft-free
•
broad tooling base
•
extensible-ish
•
broad tooling base
No Need to Start From Scratch!
YAML

34. Introducing: RAML
A new open spec
for RESTful APIs
that's as clean
and as structured
as REST itself
RESTful API Modeling Language
the RAML Workgroup:
raml.org

35. /users:
get:
description: Get a collection of users
post:
description: Create a new user in the collection
/users/{userId}:
get:
description: Get a single user
put:
description: Update a single user
delete:
description: Delete a single user
RAML: How Clean? How Structured?
Take what you would have typed yourself…

36. RAML: How Clean? How Structured?

37. RAML: How Clean? How Structured?

38. RAML: How Clean? How Structured?
resource type
schema
trait

39. Covers Full HTTP
optional version in baseUri
template URIs
query parameters
headers (on request and
response)
response per status code
example (and schema) per media
type

40. Patterns: Resource Types
externalizable
inheritance
pull in
traits
parametriz
e

41. Patterns: Method-level traits
mix-ins

42. Patterns: body schemas
or just use good ol'
form data:
XML schema
JSON schema
examples

43. RAML for Real-Time APX Design
DEMO

44. raml.org

45. q
open-source tooling; host it too (e.g. on APIhub)
q
growing library of API specs in RAML (e.g. on APIhub)
q
converters
q
client generators
q
server frameworks (e.g. MuleSoft APIkit; node.js)
q
testing frameworks
q
mocking services (e.g. on APIhub)
q
<insert your ideas here>
q
evolve RAML spec (RAML workgroup)
What's next?