teach a dog to rest
DESCRIPTION
this is an old version. new version here: http://blog.apigee.com/detail/slides_for_restful_api_design_second_edition_webinar/ It's been 10 years since Fielding first defined REST. So, where are all the elegant REST APIs? While many claim REST has arrived, many APIs in the wild exhibit arbitrary, productivity-killing deviations from true REST. We'll start with a typical poorly-designed API and iterate it into a well-behaved RESTful API.TRANSCRIPT
Teach a Dog to REST
Brian Mulloy@landlessness
Apigee@apigee
20%
Application developers are kingmakers.
Make your API easy to learn.
Good APIs are a design problem.
Idempotent methods
I won’t say things like that.
Let’s look at puppies.
hackett hackett
hackett hackett
.../getAllDogs/locationVerify/foodNeeded/createRecurringDogWalk/giveDirectOrder/healthCheck/getRecurringDogWalkSchedule/getLocation/getDog/massDogParty/getNewDogsSince/getRedDogs/getSittingDogs/dogStateChangesSearch/replaceSittingDogsWithRunningDogs/saveDog...
A puppy’s world is big.
JnL law_keven
Smithsonian's National Zoo hackett
...
/getAllLeashedDogs
/verifyVeterinarianLocation
/feedNeededFood
/createRecurringMedication
/doDirectOwnerDiscipline
/doExpressCheckupWithVeterinarian
/getRecurringFeedingSchedule
/getHungerLevel
/getSquirrelChasingPuppies
/newDogForOwner
/getNewDogsAtKennelSince
/getRedDogsWithoutSiblings
/getSittingDogsAtPark
/setLeashedDogStateTo
/replaceParkSittingDogsWithRunningDogs
/saveMommaDogsPuppies
...
...
/getAllDogs
/verifyLocation
/feedNeeded
/createRecurringWakeUp
/giveDirectOrder
/checkHealth
/getRecurringWakeUpSchedule
/getLocation
/getDog
/newDog
/getNewDogsSince
/getRedDogs
/getSittingDogs
/setDogStateTo
/replaceSittingDogsWithRunningDogs
/saveDog
...
We are on a slippery slope.
Keep the simple things simple.
Hopkinsii
We only need two URLs.
The first is for a collection.
/dogs
The second is for an element.
/dogs/bo
POSTGETPUTDELETE
CREATEREADUPDATEDELETE
POSTcreate
GETread
PUTupdate
DELETEdelete
create a new dog list dogs
replace dogs with new dogs
delete all dogs
treat as a collection create new dog in it
show Bo
if exists update Bo
if not create Bo
delete Bo
Resource
/dogs
/dogs/bo
Wikipedia
POSTcreate
GETread
PUTupdate
DELETEdelete
create a new dog list dogs
replace dogs with new dogs
delete all dogs
treat as a collection create new dog in it
show Bo
if exists update Bo
if not create Bo
delete Bo
Resource
/dogs
/dogs/bo
Wikipedia
POSTcreate
GETread
PUTupdate
DELETEdelete
create a new dog list dogs
bulk update dogs
delete all dogs
error show Bo
if exists update Bo
if noterror
delete Bo
Resource
/dogs
/dogs/bo
Wikipedia
Verbs are bad.
Nouns are good.
Plurals are better.
What about associations?
GET /owners/bob/dogs
POST /owners/bob/dogs
What about complex variations?
Cody Simms
Sweep variations under the ‘?’
/dogs?color=red&state=running&location=park
What about pagination?
offsetlimit
pagerpp
startcount
/dogs?limit=25&offset=50
What about searching?
/search?q=fluffy+dog
Global
/owners/bob/dogs/search?q=fluffy
Scoped
What about versioning?
/2010-04-01/Accounts/
Twilio
/services/data/v20.0/sobjects/Account
salesforce.com
?v=1.0
/v1/dogs
Please give me exactly what I need.
/people:(id,first-name,last-name,industry)
/joe.smith/friends?fields=id,name,picture
?fields=title,media:group(media:thumbnail)
Google (partial response)
/dogs?fields=name,color,location
What about formats?
?alt=json
Google Data
/venue.json
Foursquare
Accept: application/json
Digg*
?type=json
* The type argument, if present, overrides the Accept header.
/dogs.json
/dogs/bo.json
What about partial updates?
What about errors?
meredithfarmer
Facebook{"type":"OAuthException","message":"(#803) Some
of the aliases you requested do not exist:
foo.bar"}
HTTP Status Code: 200
{"status":401,"message":"Authenticate","code":
20003,"more_info":"http://www.twilio.com/docs/
errors/20003"}
Twilio HTTP Status Code: 401
{"code":401,"message":"Authentication
Required"}
SimpleGeo HTTP Status Code: 401
200 - OK
{“message” : “Verbose, plain language description of the problem with hints about how to fix it.”“more_info” : “http://dev.teachdogrest.com/errors/12345”}
Code for code
Message for people
401 - Unauthorized
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
What about the rest of the URL?
api.foursquare.comFoursquaredevelopers.foursquare.com
graph.facebook.comFacebook
developers.facebook.com
api.twitter.comTwittersearch.twitter.com
api.facebook.com
dev.twitter.com
stream.twitter.com
api.teachdogrest.com
dev.teachdogrest.com
API gateway
Developer connection
api ! dev
Do web redirects
developers ! devdeveloper ! dev
What about defaults?
json
Format
Pagination (depends on data size)
limit=10&offset=0
What about exceptional stuff?
Client intercepts HTTP error codes
{"error" : "Could not authenticate you." }
HTTP Status Code: 200
/public_timelines.json?suppress_response_codes=true
200 - OK
Code for code ignoring
{“response_code” : “401”, “message” : “Verbose, plain language description of the problem with hints about how to fix it.”“more_info” : “http://dev.teachdogrest.com/errors/12345”, “code” : 12345}
Message for people code
/dogs?suppress_response_codes=true
Always returns OK
Client supports limited HTTP methods
Method Parameter
/dogs?method=postcreate
/dogs
read
/dogs/bo?method=put&location=parkupdate
/dogs/bo?method=deletedelete
Really? All of this? And iterate it?
API Virtualization Layer
Application
APIAPI API
Be RESTfulOnly 2 URLsNo verbsUse nouns as pluralsSweep complexity behind the ‘?’Borrow from leading APIsAccount for exceptional clientsAdd virtualization layer
