Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Pragma&c
RESTBeware
of
DogmaMarsh
Gardiner@earth2marshBrian
Mulloy@landlessnessApigee@apigee
#apidesign             2
3
What
is
Pragma&c
REST?
What
is
Pragma&c
REST?• Not strict REST
What
is
Pragma&c
REST?• Not strict REST• Adoption-centered design
Why
REST
is
winning:
Why
REST
is
winning:http://api.twitter.com/1/statuses/public_timeline.json
POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: 299<?xml versi...
URLs
and
Verbs
URLs
and
Verbs• URL is the LCD
URLs
and
Verbs• URL is the LCD• Verbs map to CRUD
Good Architecture !   Good Design
“   As
the
flexibility
of
a
system
increases,
its
usability
    decreases.                   Flexibility‐Usability
Tradeoff ...
“   Successful
products
typically
follow
four
stages
of
creaEon:
    requirements,
design,
development,
and
tes&ng.       ...
We
only
need
two
URLs.
The
first
is
for
a
collecEon.
/dogs
The
second
is
for
an
element.
/dogs/1234
POSTGETPUTDELETE
CREATEREADUPDATEDELETE
Resource      POST             GET        PUT         DELETE              create           read      update        delete ...
Verbs
are
bad.
Nouns
are
good.
Plurals
are
beNer.
What
about
associaEons?
GET /owners/9876/dogsPOST /owners/9876/dogs
What
about
complex
variaEons?
Cody Simms
Sweep
variaEons
under
the
‘?’
/dogs?color=red&state=running&location=park
What
about
paginaEon?
FacebookoffsetlimitTwiNerpagerppLinkedInstartcount
/dogs?limit=25&offset=50
What
about
versioning?
earth2marsh
Twilio/2010-04-01/Accounts/salesforce.com/services/data/v20.0/sobjects/AccountFacebook?v=1.0
/v1/dogs
Please
give
me
exactly
what
I
need.
LinkedIn/people:(id,first-name,last-name,industry)Facebook
/joe.smith/friends?fields=id,name,pictureGoogle
(parEal
respons...
/dogs?fields=name,color,location
What
about
formats?
Google
Data?alt=jsonFoursquare/venue.jsonDigg*Accept: application/json?type=json* The type argument, if present, overrides...
“   The
Eme
it
takes
to
make
a
decision
increases
as
the
    number
of
alternaEves
increases.                             ...
/dogs.json/dogs/bo.json
What
about
searching?
Global/search?q=fluffy+dogScoped/owners/bob/dogs/search?q=fluffyFormaNed/search.xml?q=fluffy
What
about
errors?
earth2marsh
Facebook            HTTP Status Code: 200{"type":"OAuthException","message":"(#803) Someof the aliases you requested do no...
Code
for
code200 - OK401 - Unauthorizedhttp://en.wikipedia.org/wiki/List_of_HTTP_status_codesMessage
for
people{“message” ...
What
about
the
rest
of
the
URL?
Facebook    graph.facebook.com             api.facebook.com             developers.facebook.comFoursquare   api.foursquare...
API
gatewayapi.teachdogrest.comDeveloper
connecEondevelopers.teachdogrest.comDo
web
redirectsapi → developers (if from bro...
What
about
defaults?
FormatjsonPaginaEon
(depends
on
data
size)limit=10&offset=0
What
about
excepEonal
stuff?
MiguelVieira
Client
intercepts
HTTP
error
codes
TwiNer/public_timelines.json?suppress_response_codes=trueHTTP Status Code: 200{"error" : "Could not authenticateyou." }
Always
returns
OK/dogs?suppress_response_codes=trueCode
for
code
ignoring200 - OKMessage
for
people
code{“response_code” :...
Client
supports
limited
HTTP
methods
Method
Parametercreate/dogs?method=postread/dogsupdate/dogs/bo?method=put&location=parkdelete/dogs/bo?method=delete
Really?
All
of
this?
And
iterate
it?
Application      API Virtualization LayerAPI             API              API
Be
RESTfulOnly
2
URLsNo
verbsUse
nouns
as
pluralsSweep
complexity
behind
the
‘?’Borrow
from
leading
APIsAccount
for
excepE...
THANK
YOUQues%ons
and
ideas
to:#apidesignMarsh
Gardiner           Brian
Mulloy@earth2marsh             @landlessnessmarsh@...
Pragmatic RESTful API Design: Apigee Webinar
Pragmatic RESTful API Design: Apigee Webinar
Pragmatic RESTful API Design: Apigee Webinar
Pragmatic RESTful API Design: Apigee Webinar
Pragmatic RESTful API Design: Apigee Webinar
Upcoming SlideShare
Loading in …5
×

Pragmatic RESTful API Design: Apigee Webinar

102,756 views

Published on

RESTful API design principle webinar by apigee. Check out our blog for the recording and video, thanks!

Published in: Technology, Lifestyle
  • Be the first to comment

Pragmatic RESTful API Design: Apigee Webinar

  1. 1. Pragma&c
RESTBeware
of
DogmaMarsh
Gardiner@earth2marshBrian
Mulloy@landlessnessApigee@apigee
  2. 2. #apidesign 2
  3. 3. 3
  4. 4. What
is
Pragma&c
REST?
  5. 5. What
is
Pragma&c
REST?• Not strict REST
  6. 6. What
is
Pragma&c
REST?• Not strict REST• Adoption-centered design
  7. 7. Why
REST
is
winning:
  8. 8. Why
REST
is
winning:http://api.twitter.com/1/statuses/public_timeline.json
  9. 9. POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: 299<?xml version="1.0"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> </soap:Header> <soap:Body> <m:GetStockPrice xmlns:m="http://www.example.org/stock"> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body></soap:Envelope>
  10. 10. URLs
and
Verbs
  11. 11. URLs
and
Verbs• URL is the LCD
  12. 12. URLs
and
Verbs• URL is the LCD• Verbs map to CRUD
  13. 13. Good Architecture ! Good Design
  14. 14. “ As
the
flexibility
of
a
system
increases,
its
usability
 decreases. Flexibility‐Usability
Tradeoff Universal
Principles
of
Design
  15. 15. “ Successful
products
typically
follow
four
stages
of
creaEon:
 requirements,
design,
development,
and
tes&ng. Development
Cycle Universal
Principles
of
Design
  16. 16. We
only
need
two
URLs.
  17. 17. The
first
is
for
a
collecEon.
  18. 18. /dogs
  19. 19. The
second
is
for
an
element.
  20. 20. /dogs/1234
  21. 21. POSTGETPUTDELETE
  22. 22. CREATEREADUPDATEDELETE
  23. 23. Resource POST GET PUT DELETE create read update delete create
a
new
 bulk
update
 delete
all
 /dogs list
dogs dog dogs dogs if
exists
 update
Bo/dogs/bo error show
Bo delete
Bo if
not error Wikipedia
  24. 24. Verbs
are
bad.
  25. 25. Nouns
are
good.
  26. 26. Plurals
are
beNer.
  27. 27. What
about
associaEons?
  28. 28. GET /owners/9876/dogsPOST /owners/9876/dogs
  29. 29. What
about
complex
variaEons?
  30. 30. Cody Simms
  31. 31. Sweep
variaEons
under
the
‘?’
  32. 32. /dogs?color=red&state=running&location=park
  33. 33. What
about
paginaEon?
  34. 34. FacebookoffsetlimitTwiNerpagerppLinkedInstartcount
  35. 35. /dogs?limit=25&offset=50
  36. 36. What
about
versioning?
  37. 37. earth2marsh
  38. 38. Twilio/2010-04-01/Accounts/salesforce.com/services/data/v20.0/sobjects/AccountFacebook?v=1.0
  39. 39. /v1/dogs
  40. 40. Please
give
me
exactly
what
I
need.
  41. 41. LinkedIn/people:(id,first-name,last-name,industry)Facebook
/joe.smith/friends?fields=id,name,pictureGoogle
(parEal
response)
?fields=title,media:group(media:thumbnail)
  42. 42. /dogs?fields=name,color,location
  43. 43. What
about
formats?
  44. 44. Google
Data?alt=jsonFoursquare/venue.jsonDigg*Accept: application/json?type=json* The type argument, if present, overrides the Accept header.
  45. 45. “ The
Eme
it
takes
to
make
a
decision
increases
as
the
 number
of
alternaEves
increases. Hick’s
Law Universal
Principles
of
Design
  46. 46. /dogs.json/dogs/bo.json
  47. 47. What
about
searching?
  48. 48. Global/search?q=fluffy+dogScoped/owners/bob/dogs/search?q=fluffyFormaNed/search.xml?q=fluffy
  49. 49. What
about
errors?
  50. 50. earth2marsh
  51. 51. Facebook HTTP Status Code: 200{"type":"OAuthException","message":"(#803) Someof the aliases you requested do not exist:foo.bar"}Twilio HTTP Status Code: 401{"status":401,"message":"Authenticate","code":20003,"more_info":"http://www.twilio.com/docs/errors/20003"}SimpleGeo HTTP Status Code: 401{"code":401,"message":"AuthenticationRequired"}
  52. 52. Code
for
code200 - OK401 - Unauthorizedhttp://en.wikipedia.org/wiki/List_of_HTTP_status_codesMessage
for
people{“message” : “Verbose, plain languagedescription of the problem with hints abouthow to fix it.”“more_info” : “http://dev.teachdogrest.com/errors/12345”}
  53. 53. What
about
the
rest
of
the
URL?
  54. 54. Facebook graph.facebook.com api.facebook.com developers.facebook.comFoursquare api.foursquare.com developers.foursquare.com TwiNer api.twitter.com search.twitter.com stream.twitter.com dev.twitter.com
  55. 55. API
gatewayapi.teachdogrest.comDeveloper
connecEondevelopers.teachdogrest.comDo
web
redirectsapi → developers (if from browser)dev → developersdeveloper → developers
  56. 56. What
about
defaults?
  57. 57. FormatjsonPaginaEon
(depends
on
data
size)limit=10&offset=0
  58. 58. What
about
excepEonal
stuff?
  59. 59. MiguelVieira
  60. 60. Client
intercepts
HTTP
error
codes
  61. 61. TwiNer/public_timelines.json?suppress_response_codes=trueHTTP Status Code: 200{"error" : "Could not authenticateyou." }
  62. 62. Always
returns
OK/dogs?suppress_response_codes=trueCode
for
code
ignoring200 - OKMessage
for
people
code{“response_code” : “401”, “message” :“Verbose, plain language description of theproblem with hints about how to fix it.”“more_info” : “http://dev.teachdogrest.com/errors/12345”, “code” : 12345}
  63. 63. Client
supports
limited
HTTP
methods
  64. 64. Method
Parametercreate/dogs?method=postread/dogsupdate/dogs/bo?method=put&location=parkdelete/dogs/bo?method=delete
  65. 65. Really?
All
of
this?
And
iterate
it?
  66. 66. Application API Virtualization LayerAPI API API
  67. 67. Be
RESTfulOnly
2
URLsNo
verbsUse
nouns
as
pluralsSweep
complexity
behind
the
‘?’Borrow
from
leading
APIsAccount
for
excepEonal
clientsAdd
virtualizaEon
layer
  68. 68. THANK
YOUQues%ons
and
ideas
to:#apidesignMarsh
Gardiner Brian
Mulloy@earth2marsh @landlessnessmarsh@apigee.com brian@apigee.com

×