RAML – APIs By Design
#RAML

Uri Sarid
CTO, MuleSoft

@MuleSoft

@usarid
APIs:
The Cat's Meow
Ultimate Buzz for Creatively-lazy Developers

build on someone else's work… who's?
14000
12000

open APIs

10000
8000
6000...
Modularity, Encapsulation, Specialization

yes, even Service-Oriented Architecture!
 eCommerce
 products
 shopping cart...
The API Economy Is Big and It's Now

>13,000

Open APIs
Enterprise APIs

1,000,000s
APIs and me
My Experience:

consumer
portal

utility
back-office
software
The API Contract Is Critical

• tells consumer devs what they'll get

• tells implementer devs what to deliver

• enables ...
My Experience: Barnes & Noble /

the layer cake
of APIs

Don't expose dirty laundry



users

products
orders



invoice...
At MuleSoft

connectivity
The traditional enterprise
sits comfortably behind the firewall

Packaged apps

Custom apps

The Traditional Enterprise

D...
Welcome to the New Enterprise

SaaS
Social

Cloud platforms

Mobility and Devices

Customers / Partners / Suppliers

Packa...
Connect backend

SaaS
Social

Cloud platforms

Mobility and Devices

Customers / Partners / Suppliers

Packaged apps

Cust...
Backend to SaaS

SaaS
Social

Cloud platforms

Mobility and Devices

Customers / Partners / Suppliers

Packaged apps

Cust...
Everything needs to connect

SaaS
Social

Cloud platforms

Mobility and Devices

Customers / Partners / Suppliers

Package...
The Anypoint Platform:
integration on-premises and cloud

SaaS
Cloud platforms

Social

Anypoint Platform
Mobility and Dev...
The Anypoint Platform:
integration on-premises and cloud

1,000s
100s

SaaS

1,000,000s

Cloud platforms

100,000s

Social...
The Anypoint Platform for APIs

SaaS
Cloud platforms

Social

Anypoint Platform
Design/Dev Portal

API Manager

APIkit

An...
An Opinionated Approach to
API Success
The Key to API Success?

how?
•
•
•
•

design for them
iterate quickly
model cleanly and consistently
engage
Design For Your Users

UI  UX
Capture
Feedback

API  APX
Focus on the Interface: The Contract

 where consumers touch you

 your front door, your lobby, your façade
 how you wa...
What kind of interface do we want?

1. Describe APIs simply and clearly

2. Design APIs easily and soundly
3. Engage users...
Practically-RESTful APIs

•
•
•
•
•
•

nouns: resources, described by URI paths
verbs: HTTP methods
metadata: HTTP headers...
What Do People Do Today?
WADL
Reverb Swagger
Mashery IOdocs
Google Discovery Docs
Apiary Blueprint
Verdict:

manifest
structure

capture
patterns

humanly
writeable

let's try
harder…
Start From Scratch?
Really???
No Need to Start From Scratch!

•
•
•
•
•
•
•

well-known superset of JSON
optimized for human readability
great for hiera...
Introducing: RAML

RESTful API Modeling Language
A new open spec
for RESTful APIs
that's as clean
and as structured
as RES...
RAML: How Clean? How Structured?

Take what you would have typed yourself…
/users:
get:
description:
post:
description:
/u...
RAML: How Clean? How Structured?
RAML: How Clean? How Structured?
RAML: How Clean? How Structured?

resource type

schema

trait
Covers Full HTTP

optional version in baseUri

template URIs

query parameters

headers (on request and response)
response...
Patterns: Resource Types

externalizable
inheritance
pull in traits

parametrize
Patterns: Method-level traits

mix-ins
Patterns: body schemas
XML schema
JSON schema

or just use good ol'
form data:

examples
RAML for Real-Time APX Design
raml.org
What's next?

 open-source tooling; host it too (e.g. on APIhub)
 growing library of API specs in RAML (e.g. on APIhub)
...
One More Thing…
Upcoming SlideShare
Loading in...5
×

RAML - APIs By Design

3,144

Published on

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

Published in: Technology

RAML - APIs By Design

  1. 1. RAML – APIs By Design #RAML Uri Sarid CTO, MuleSoft @MuleSoft @usarid
  2. 2. APIs: The Cat's Meow
  3. 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. 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. 5. The API Economy Is Big and It's Now >13,000 Open APIs Enterprise APIs 1,000,000s
  6. 6. APIs and me
  7. 7. My Experience: consumer portal utility back-office software
  8. 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. 9. My Experience: Barnes & Noble / the layer cake of APIs Don't expose dirty laundry  users products orders  invoices
  10. 10. At MuleSoft connectivity
  11. 11. The traditional enterprise sits comfortably behind the firewall Packaged apps Custom apps The Traditional Enterprise Databases
  12. 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. 13. Connect backend SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  14. 14. Backend to SaaS SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  15. 15. Everything needs to connect SaaS Social Cloud platforms Mobility and Devices Customers / Partners / Suppliers Packaged apps Custom apps The New Enterprise Databases
  16. 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. 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. 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. 19. An Opinionated Approach to API Success
  20. 20. The Key to API Success? how? • • • • design for them iterate quickly model cleanly and consistently engage
  21. 21. Design For Your Users UI  UX Capture Feedback API  APX
  22. 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. 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. 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. 25. What Do People Do Today?
  26. 26. WADL
  27. 27. Reverb Swagger
  28. 28. Mashery IOdocs
  29. 29. Google Discovery Docs
  30. 30. Apiary Blueprint
  31. 31. Verdict: manifest structure capture patterns humanly writeable let's try harder…
  32. 32. Start From Scratch? Really???
  33. 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. 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. 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. 36. RAML: How Clean? How Structured?
  37. 37. RAML: How Clean? How Structured?
  38. 38. RAML: How Clean? How Structured? resource type schema trait
  39. 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. 40. Patterns: Resource Types externalizable inheritance pull in traits parametrize
  41. 41. Patterns: Method-level traits mix-ins
  42. 42. Patterns: body schemas XML schema JSON schema or just use good ol' form data: examples
  43. 43. RAML for Real-Time APX Design
  44. 44. raml.org
  45. 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. 46. One More Thing…
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×