5 keys to api design - api days paris 2013
TRANSCRIPT
![Page 1: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/1.jpg)
5 Keys to API Design Daniel Feist
Principal Architect, MuleSoft
@MuleSoft
@dfeist
![Page 2: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/2.jpg)
Me?
![Page 3: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/3.jpg)
Me?
![Page 4: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/4.jpg)
Me?
![Page 5: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/5.jpg)
Me?
![Page 6: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/6.jpg)
APIs: The Cat's Meow
![Page 7: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/7.jpg)
7 All contents Copyright © 2013, MuleSoft Inc.
The New Enterprise
![Page 8: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/8.jpg)
The New Enterprise
SaaS
Packaged apps Custom apps Big Databases / Big Files
Social Cloud platforms
Customers / Partners / Suppliers
Mobility and Devices
![Page 9: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/9.jpg)
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
![Page 10: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/10.jpg)
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
![Page 11: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/11.jpg)
API Design
![Page 12: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/12.jpg)
#1 The Contract is Critical
![Page 13: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/13.jpg)
• 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
![Page 14: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/14.jpg)
ü 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
![Page 15: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/15.jpg)
1. Describe APIs simply and clearly
2. Design APIs easily and soundly
What kind of contract do we want?
![Page 16: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/16.jpg)
Document your API?
What kind of contract do we want?
or
Model your API?
![Page 17: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/17.jpg)
#2 Design to Delight
![Page 18: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/18.jpg)
The Key to API Success?
how?
• design for them • iterate quickly • model cleanly and consistently • gather feedback
![Page 19: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/19.jpg)
#3 Think APX not API
![Page 20: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/20.jpg)
Valid
ate
Capture Feedback
UI à UX
API à APX
Design For Your Users
![Page 21: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/21.jpg)
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
![Page 22: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/22.jpg)
#4 Use Patterns
![Page 23: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/23.jpg)
Pattern Lifecycle
Define Share Reuse
![Page 24: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/24.jpg)
• Resource Types • Collection • Collection Member • Document
• Traits • Secure • Paged
Types of Patterns
![Page 25: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/25.jpg)
#5 Engage Developers
![Page 26: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/26.jpg)
• Social Tools • Rate, discuss • Provide feedback
• Interactive Console
• Prototyping Tools
Engage Developers
![Page 27: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/27.jpg)
![Page 28: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/28.jpg)
What Do People Do Today?
![Page 29: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/29.jpg)
WADL
![Page 30: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/30.jpg)
Reverb Swagger
![Page 31: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/31.jpg)
Mashery IOdocs
![Page 32: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/32.jpg)
Google Discovery Docs
![Page 33: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/33.jpg)
Apiary Blueprint
![Page 34: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/34.jpg)
Verdict:
manifest structure
capture patterns
humanly writeable
let's try harder…
![Page 35: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/35.jpg)
Start From Scratch? Really???
![Page 36: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/36.jpg)
• 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!
![Page 37: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/37.jpg)
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
![Page 38: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/38.jpg)
RAML: How Clean? How Structured?
![Page 39: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/39.jpg)
RAML: Clean & Structured.
![Page 40: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/40.jpg)
RAML: Reuse
resource type schema
trait
![Page 41: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/41.jpg)
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
![Page 42: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/42.jpg)
Patterns: Resource Types
externalizable
inheritance
pull in traits
parametrize
![Page 43: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/43.jpg)
Patterns: Method-level traits
mix-ins
![Page 44: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/44.jpg)
Patterns: body schemas
or just use good ol' form data:
XML schema
JSON schema
examples
![Page 45: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/45.jpg)
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
![Page 46: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/46.jpg)
![Page 47: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/47.jpg)
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?
![Page 48: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/48.jpg)
![Page 49: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/49.jpg)
Interesting?
![Page 50: 5 Keys to API Design - API Days Paris 2013](https://reader034.vdocuments.site/reader034/viewer/2022052321/554fb296b4c90586258b5249/html5/thumbnails/50.jpg)
Thank you!