5 keys to api design - api days paris 2013
TRANSCRIPT
5 Keys to API Design Daniel Feist
Principal Architect, MuleSoft
@MuleSoft
@dfeist
Me?
Me?
Me?
Me?
APIs: The Cat's Meow
7 All contents Copyright © 2013, MuleSoft Inc.
The New Enterprise
The New Enterprise
SaaS
Packaged apps Custom apps Big Databases / Big Files
Social Cloud platforms
Customers / Partners / Suppliers
Mobility and Devices
SaaS
Packaged apps Custom apps Big Databases / Big Files
Social Cloud platforms
Customers / Partners / Suppliers
Mobility and Devices
100,000s
100s 1,000s
1,000,000s
1,000,000,000s
The New Enterprise
SaaS
Packaged apps Custom apps Databases
Social Cloud platforms
Customers / Partners / Suppliers Mobility and Devices
The New Enterprise
Internal APIs
B2B APIs
Open web APIs
Product APIs
The New Enterprise
API Design
#1 The Contract is Critical
• 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
ü 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
The Contract is Critical
1. Describe APIs simply and clearly
2. Design APIs easily and soundly
What kind of contract do we want?
Document your API?
What kind of contract do we want?
or
Model your API?
#2 Design to Delight
The Key to API Success?
how?
• design for them • iterate quickly • model cleanly and consistently • gather feedback
#3 Think APX not API
Valid
ate
Capture Feedback
UI à UX
API à APX
Design For Your Users
Think APX!
Don't expose dirty laundry
users
products
orders invoices
è!
Craft it for your users: what will they love?
This is a long-lived interface, ladies and gentlemen
#4 Use Patterns
Pattern Lifecycle
Define Share Reuse
• Resource Types • Collection • Collection Member • Document
• Traits • Secure • Paged
Types of Patterns
#5 Engage Developers
• Social Tools • Rate, discuss • Provide feedback
• Interactive Console
• Prototyping Tools
Engage Developers
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
No Need to Start From Scratch!
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
RAML: How Clean? How Structured?
RAML: Clean & Structured.
RAML: Reuse
resource type schema
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
Patterns: security schemes
username/password; cleartext or use digest
end user allows app to access their data
better to put token in header, not query
the OAuth multi-step dance
q growing library of API specs in RAML (e.g. on APIhub) q converters (import WADL, Swagger etc.) q client generators q server frameworks (e.g. MuleSoft APIkit; node.js) q JAX-RS Support q testing frameworks q mocking services (e.g. on APIhub) q <insert your ideas here>
q evolve RAML spec (RAML workgroup)
What's next?
Interesting?
Thank you!