api design: an adoption-centered approach
DESCRIPTION
Application developers are the customers of your API. Success is measured by how quickly those developers enjoy success using your API in their applications. And rapid adoption of an API by your internal, partner, or external developers is all about design. Building upon their prior work in API design, Marsh Gardiner and Brian Mulloy unveil RV, a style of API design that embraces developer adoption as its guiding principle. They explore the constraints and opportunities introduced by RV and discuss RV's place in the context of other design approaches like REST and Hypermedia. See the youtube video of this webcast https://www.youtube.com/watch?v=u-bGz9HQIuoTRANSCRIPT
API Design
Brian Mulloy@landlessness
Marsh Gardiner@earth2marsh
An Adoption-Centered Approach
@landlessnessBrian Mulloy
@earth2marshMarsh Gardiner
http://iloveapis2014.com
groups.google.com/group/api-craft
youtube.com/apigee
slideshare.net/apigee
Integers as a Service
Overview
• How did we get here?• Where are we now?• Where are we going?• How are we going to get there?• Questions
How did we get here?
In the beginning…
SOAP and XML-RPC
REST
The rise of…• Software as a Service• Web Mashups• Virtualization• User Experience• Mobile
Web vs App
Technology unlocks technology…
Gehry vs Winnebago
photo: uggboy
Where are we now?
Refocusing API design
Passion (and controversy)
API Craft Conferencehttp://api-craft.org
Monday, July 28th – Wednesday July 30th
Hypermedia PanelAPI Craft Conference - http://api-craft.org
• Collection+JSON– Mike Amundsen
• Hydra– Markus Lanthaler
• Mason– Jørn Wildt
• HAL– Mike Kelly
• JSON API– Steve Klabnik
• Siren– Kevin Swiber
Gehry vs Winnebago
photo: uggboy
Designing for adoption
Resource(a thing that lives somewhere)
26
IP: 173.194.70.102 google.com➡Twitter: 14352786 @earth2marsh➡
https://github.com/apigee
Verb
Applying RV patterns
Collections and entitieshttps://api.stripe.com/
Summary of Resource URL Patterns/v1/charges/v1/charges/{CHARGE_ID}/v1/coupons/v1/coupons/{COUPON_ID}/v1/customers/v1/customers/{CUSTOMER_ID}
Versions
/2010-04-01/Accounts/Twilio
/services/data/v29.0/sobjects/Account
Salesforce
/v2/usersFoursquare
Query Parameters
/1.1/search/tweets.json?q=%23superbowl &result_type=recent
Header Parameters
Conveniences
/meFacebook
/v1/people/~LinkedIn
/v2/checkins/recentFoursquare
Formats
/users/3207.json
SoundCloud/users/3207
Formats
Actions
/search?q=watermelon&type=post
/convert?from=EUR&to=CNY&amount=100(hypothetical)
/droplets/{droplet_id}/rebootDigitalOcean
Authentication
Dates
"created_at": "Thu Nov 03 05:19:38 +0000 2011"
"DateTime": "2011-10-29T09:35:00Z"Bing
"createdAt": 1320296464Foursquare
Filters
/me?fields=name,birthday,photos.limit(10) .fields(id,picture),videos.type(tagged) .limit(10).fields(id, source)
offset, limitFacebook
page, rppTwitter
start, countLinkedIn
Pagination
Pagination
offset, limitFacebook
HATEOAS and the Hypermedia Constraint
Hypermedia
Great moments in mishandled error code history
Errors
SDKs
Perfect is the enemy of done
General philosophy
Questions
[email protected], @ResourceVerb
[email protected], @landlessness
[email protected], @earth2marsh
THANK YOU
Brian Mulloy@landlessness
Marsh Gardiner@earth2marsh
THANK YOUSubscribe to webcasts at:youtube.com/apigee
THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
THANK YOUWebcast slides at:slideshare.net/apigee
THANK YOU
Brian Mulloy@landlessness
Marsh Gardiner@earth2marsh