View
2.637
Download
4
Category
Preview:
DESCRIPTION
My talk (first given at HTML5 Dev Conference October 2013) about API design and RAML. See http://raml.org for more info.
Citation preview
RAML – APIs By Design
Uri Sarid
CTO, MuleSoft
#RAML
@usarid
@MuleSoft
APIs:The Cat's Meow
build on someone else's work… who's?
Ultimate Buzz for Creatively-lazy Developers
2005 2006 2007 2008 2009 2010 2011 2012 20130
2000
4000
6000
8000
10000
12000
14000
Source:
open APIs
yes, even Service-Oriented Architecture!
Modularity, Encapsulation, Specialization
eCommerceproductsshopping cartcheckoutbillingshipping
socialgraphposting
geolocationcity dataweatherattractionsbusinesses
collaborationdocumentsnotifications forums
analytics traffic logsNLPsales
marketingdemographicsSFAsocial
The API Economy Is Big and It's Now
1,000,000s
>13,000 Open APIs
Enterprise APIs
APIs and me
My Experience:
utility back-office software
consumer portal
• 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
My Experience: Barnes & Noble /
Don't expose dirty laundry
users
products
ordersinvoices
the layer cake of APIs
At MuleSoft
connectivity
Packaged apps Custom apps Databases
The Traditional Enterprise
The traditional enterprisesits comfortably behind the firewall
Welcome to the New Enterprise
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
Connect backend
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
Backend to SaaS
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
Everything needs to connect
SaaS
Packaged apps Custom apps Databases
SocialCloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
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
BusinessInsight
EnterpriseMgmt
Mule Studio
Anypoint DataMapper
DataSense
Anypoint Connectors
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
BusinessInsight
EnterpriseMgmt
Mule Studio
Anypoint DataMapper
DataSense
Anypoint Connectors
100,000s
100s1,000s
1,000,000s
1,000,000,000s
The Anypoint Platform for APIs
SaaS
Packaged apps Custom apps Big Databases / Big Files
SocialCloud platforms
Customers / Partners / Suppliers
Mobility and Devices
Anypoint Platform
BusinessInsight
EnterpriseMgmt
Studio
APIkit
Anypoint DataMapper
DataSense
API Gateway
API Manager
Design/Dev Portal
Anypoint Connectors
An Opinionated Approach to API Success
DELIGHT YOUR USERS!
The Key to API Success?
how?
• design for them• iterate quickly• model cleanly and consistently• engage
Codify
Req
’s
Design API
Val
idat
e
Publish
CaptureFeedback
UI UX
API APX
Design For Your Users
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
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
• 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…
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???
• 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
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
/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…
RAML: How Clean? How Structured?
RAML: How Clean? How Structured?
RAML: How Clean? How Structured?
resource typeschema
trait
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
Patterns: Resource Types
externalizable
inheritance
pull in traits
parametrize
Patterns: Method-level traits
mix-ins
Patterns: body schemas
or just use good ol' form data:
XML schema
JSON schema
examples
RAML for Real-Time APX Design
DEMO
raml.org
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)
What's next?
One More Thing…
NOTEBOOK DEMO
Recommended