My talk (first given at HTML5 Dev Conference October 2013) about API design and RAML. See http://raml.org for more info.

1. RAML – APIs By Design
#RAML
Uri Sarid
CTO, MuleSoft
@MuleSoft
@usarid

2. APIs:
The Cat's Meow

3. Ultimate Buzz for Creatively-lazy Developers
build on someone else's work… who's?
14000
12000
open APIs
10000
8000
6000
4000
2000
0
2005
2006
2007
2008
2009
2010
2011
2012
Source:
2013

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

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

6. APIs and me

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

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

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

10. At MuleSoft
connectivity

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

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

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

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

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

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

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

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

19. An Opinionated Approach to
API Success

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

21. Design For Your Users
UI  UX
Capture
Feedback
API  APX

22. Focus on the Interface: The Contract
 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

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

24. Practically-RESTful APIs
•
•
•
•
•
•
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

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. No Need to Start From Scratch!
•
•
•
•
•
•
•
well-known superset of JSON
optimized for human readability
great for hierarchies
cruft-free
broad tooling base
extensible-ish
broad tooling base

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

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

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
parametrize

41. Patterns: Method-level traits
mix-ins

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

43. RAML for Real-Time APX Design

44. raml.org

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

46. One More Thing…