apidesignsecondedition-111103185958-phpapp02

7/30/2019 apidesignsecondedition-111103185958-phpapp02

1/106

RESTful API DesignSecond Edition

Brian Mulloy@landlessness

Apigee@apigee

11.03.11 @ 11:03:11 PST

Dial-in or VoIP

See Details in Chat Window


2/106

groups.google.com/group/api-craft


3/106

youtube.com/apigee


4/106

To be a RESTafarian or a Pragmatist?


5/106


6/106

AppUser

APITeam

APIAppWorld ofAPIs

AppStore

InternalSystems

AppDeveloper


7/106

Application developers are raison d'trefor APIs.


8/106

Be pragmatic.For the benefit of application developers.


9/106

Pragmatic RESTful APIs are a design problem.


10/106

baddesigns.com


11/106


12/106


13/106

Paul Mijksenaar Design for Function Award 2011


14/106


15/106

Lets look at puppies.


16/106

hackett hackett

hackett hackett
http://www.flickr.com/photos/hackett/154894923/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/154894923/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/156760548/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/156760548/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/159428076/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/159428076/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/159428074/sizes/l/in/photostream/http://www.flickr.com/photos/hackett/159428074/sizes/l/in/photostream/


17/106

...

/getAllDogs

/locationVerify

/foodNeeded/createRecurringDogWalk

/giveDirectOrder

/healthCheck

/getRecurringDogWalkSchedule

/getLocation/getDog

/massDogParty

/getNewDogsSince

/getRedDogs

/getSittingDogs

/dogStateChangesSearch

/replaceSittingDogsWithRunningDogs

/saveDog

...


18/106


19/106

A puppys world is big.


20/106

JnL law_keven

Smithsonian's National Zoo hackett
http://www.flickr.com/photos/hackett/306923792/sizes/o/in/set-72157594146742722/http://www.flickr.com/photos/hackett/306923792/sizes/o/in/set-72157594146742722/http://www.flickr.com/photos/nationalzoo/4998899286/sizes/o/in/photostream/http://www.flickr.com/photos/nationalzoo/4998899286/sizes/o/in/photostream/http://www.flickr.com/photos/kevenlaw/2461340910/sizes/l/in/photostream/http://www.flickr.com/photos/kevenlaw/2461340910/sizes/l/in/photostream/http://www.flickr.com/photos/jnl/48331634/sizes/l/in/photostream/http://www.flickr.com/photos/jnl/48331634/sizes/l/in/photostream/


21/106

...

/getAllLeashedDogs

/verifyVeterinarianLocation

/feedNeededFood

/createRecurringMedication

/doDirectOwnerDiscipline

/doExpressCheckupWithVeterinarian

/getRecurringFeedingSchedule

/getHungerLevel

/getSquirrelsChasingPuppies

/newDogForOwner

/getNewDogsAtKennelSince

/getRedDogsWithoutSiblings

/getSittingDogsAtPark

/setLeashedDogStateTo

/replaceParkSittingDogsWithRunningDogs

/saveMommaDogsPuppies

...

...

/getAllDogs

/verifyLocation

/feedNeeded

/createRecurringWakeUp

/giveDirectOrder

/checkHealth

/getRecurringWakeUpSchedule

/getLocation

/getDog

/newDog

/getNewDogsSince

/getRedDogs

/getSittingDogs

/setDogStateTo

/replaceSittingDogsWithRunningDogs

/saveDog

...


22/106

We are on a slippery slope.


23/106

Keep the simple things simple.


24/106

Hopkinsii
http://www.flickr.com/photos/hopkinsii/2194298635/sizes/o/in/photostream/http://www.flickr.com/photos/hopkinsii/2194298635/sizes/o/in/photostream/


25/106

We only need two base URLs per resource.


26/106

The first is for a collection.


27/106

/dogs


28/106

The second is for an element.


29/106

/dogs/1234


30/106

POST

GETPUT

DELETE


31/106

CREATE

READUPDATE

DELETE


32/106

POSTcreate

GETread

PUTupdate

DELETEdelete

create anew dog

list dogs replacedogs withnew dogs

delete alldogs

treat as a

collectioncreate newdog in it

show Bo

if existsupdate Bo

if notcreate Bo

delete Bo

Resource

/dogs

/dogs/1234

Wikipedia
http://en.wikipedia.org/wiki/Representational_State_Transferhttp://en.wikipedia.org/wiki/Representational_State_Transfer


33/106

POSTcreate

GETread

PUTupdate

DELETEdelete

create anew dog

list dogs replacedogs withnew dogs

delete alldogs

treat as acollection

createnew dogin it

show Bo

if existsupdate Bo

if notcreate Bo

delete Bo

Resource

/dogs

/dogs/1234

Wikipedia


34/106

POSTcreate

GETread

PUTupdate

DELETEdelete

create anew dog

list dogs bulkupdatedogs

delete alldogs

error show Bo

if existsupdate Bo

if noterror

delete Bo

Resource

/dogs

/dogs/1234

Wikipedia


35/106

Verbs are bad.


36/106

Nouns are good.


37/106

Plurals or singulars?


38/106

/checkins

Foursquare

/deals

GroupOn

/Product

Zappos


39/106

Plurals are better.

/dogs


40/106

Abstract or concrete naming?


41/106

/things

/animals

/dogs

Super High

High

Medium

/beagles

Low


42/106

Concrete is better than abstract./dogs


43/106

What about associations?


44/106

GET /owners/5678/dogs

POST /owners/5678/dogs


45/106

What about complex variations?


46/106

Cody Simms
http://www.flickr.com/photos/jcodysimms/246024262/sizes/l/in/photostream/http://www.flickr.com/photos/jcodysimms/246024262/sizes/l/in/photostream/


47/106

Sweep variations under the ?


48/106

/dogs?color=red&state=running&location=park


49/106

Hopkinsii
http://www.flickr.com/photos/hopkinsii/2194298635/sizes/o/in/photostream/http://www.flickr.com/photos/hopkinsii/2194298635/sizes/o/in/photostream/


50/106

/dogs


51/106

What about errors?


52/106

meredithfarmer
http://www.flickr.com/photos/meredithfarmer/311658424/http://www.flickr.com/photos/meredithfarmer/311658424/


53/106

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
http://www.twilio.com/docs/errors/20003http://www.twilio.com/docs/errors/20003http://www.twilio.com/docs/errors/20003http://www.twilio.com/docs/errors/20003


54/106

200 - OK

{message : Verbose, plain language

description of the problem with hints abouthow 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
http://dev.teachdogrest.com/http://dev.teachdogrest.com/http://en.wikipedia.org/wiki/List_of_HTTP_status_codeshttp://en.wikipedia.org/wiki/List_of_HTTP_status_codeshttp://dev.teachdogrest.com/http://dev.teachdogrest.com/http://dev.teachdogrest.com/http://dev.teachdogrest.com/


55/106

What about versioning?


56/106

/2010-04-01/Accounts/

Twilio

/services/data/v20.0/sobjects/Account

salesforce.com

?v=1.0

Facebook


57/106

/v1/dogs


58/106

Please give me exactly what I need.


59/106

/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)
https://graph.facebook.com/bgolub?fields=id,name,picturehttps://graph.facebook.com/bgolub?fields=id,name,picture


60/106

/dogs?fields=name,color,location


61/106

What about pagination?


62/106

offsetlimit

Facebook

page

rpp

Twitter

start

count

LinkedIn


63/106

/dogs?limit=25&offset=50


64/106

What about formats?


65/106

?alt=json

Google Data

/venue.json

Foursquare

Accept: application/json

Digg*

?type=json

* The type argument, if present, overrides the Accept header.


66/106

/dogs.json

/dogs/1234.json


67/106

What about defaults?


68/106

json

Format

Pagination (depends on data size)

limit=10&offset=0


69/106

What about attribute names?


70/106

"created_at": "Thu Nov 03 05:19:38 +0000 2011"

Twitter

"DateTime": "2011-10-29T09:35:00Z"

Bing

"createdAt": 1320296464

Foursquare
https://graph.facebook.com/bgolub?fields=id,name,picturehttps://graph.facebook.com/bgolub?fields=id,name,picture


71/106

var myObject = JSON.parse(response);

JSON is for JavaScript Objects

timing = myObject.created_at;

These looks funny in JavaScript

timing = myObject.DateTime;


72/106

"createdAt": 1320296464

JavaScript Convention

Medial Capitalization aka CamelCase

timing = myObject.createdAt;


73/106

What about non-resource-y stuf

?


74/106

Calculate

Translate

Convert


75/106

/convert?from=EUR&to=CNY&amount=100

Use verbs not nouns


76/106

What about searching?


77/106

/search?q=fluffy+fur

Global

/owners/5678/dogs/search?q=fluffy+furScoped

/search.xml?q=fluffy+fur

Formatted


78/106

What about counts?


79/106

/dogs/count


80/106

What about the rest of the URL?

graph.facebook.comFacebook


81/106

api.foursquare.comFoursquare

developers.foursquare.com

g pFacebook

developers.facebook.com

api.twitter.comTwitter

search.twitter.com

api.facebook.com

dev.twitter.com

stream.twitter.com


82/106

api.teachdogrest.com

developers.teachdogrest.com

API gateway

Developer connection

api ! developers (if from browser)

Do web redirects

dev ! developers

developer ! developers


83/106

What about exceptional stuf

?


84/106

Client intercepts HTTP error codes


85/106

{"error" : "Could not authenticate

you." }

Twitter

HTTP Status Code: 200

/public_timelines.json?

suppress_response_codes=true

Al t OK


86/106

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
http://dev.teachdogrest.com/http://dev.teachdogrest.com/http://dev.teachdogrest.com/http://dev.teachdogrest.com/http://dev.teachdogrest.com/http://dev.teachdogrest.com/


87/106

Client supports limited HTTP methods


88/106

Method Parameter

/dogs?method=post

create

/dogs

read

/dogs/1234?method=put&location=park

update

/dogs/1234?method=delete

delete


89/106

What about authentication?


90/106

Permissions Service API

PayPal

OAuth 2.0

Facebook

OAuth 1.0aTwitter


91/106

OAuth 2.0

Use latest and greatest OAuth

Dont do something close, but diferent.


92/106

How do application developers use the API?


93/106

What about chatty applications?


94/106

First be complete & RESTful.

Then provide shortcuts.


95/106

/owners/5678?fields=name,dogs(name)

Partial response syntax can help.


96/106

What about when building an UIrequires a lot of domain knowledge?


97/106


98/106

Complement your API with codelibraries and SDK.


99/106

Really? All of this? And iterate it?


100/106


101/106

API Virtualization Layer

Application

APIAPI API


102/106

Be RESTfulOnly 2 URLsNo verbsUse nouns as plurals

Concrete over abstractFor JSON follow JavaScript conventionsSweep complexity behind the ?Borrow from leading APIs

Account for exceptional clientsAdd virtualization layer


103/106

Questions?


104/106

THANK YOUSubscribe to API webinars at:

youtube.com/apigee


105/106

THANK YOUQuestions and ideas to:

groups.google.com/group/api-craft


106/106

THANK YOUContact me at:

@landlessness

[email protected]
mailto:[email protected]:[email protected]

Documents

apidesignsecondedition-111103185958-phpapp02