teach a dog to rest

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

Facebook

pagerpp

Twitter

startcount

LinkedIn

/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

Facebook

/v1/dogs

Please give me exactly what I need.

/people:(id,first-name,last-name,industry)

LinkedIn

/joe.smith/friends?fields=id,name,picture

Facebook

?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." }

Twitter

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

THANK YOUQuestions and ideas to:

Brian Mulloy@landlessnessbrian@apigee.com