Pragmatic RESTful API Design: Apigee Webinar

100,887 views
100,601 views

Published on

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

Published in: Technology, Lifestyle
0 Comments
54 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
100,887
On SlideShare
0
From Embeds
0
Number of Embeds
23,575
Actions
Shares
0
Downloads
536
Comments
0
Likes
54
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • http://www.nordsc.com/ext/classification_of_http_based_apis.html\n
  • \n
  • Here’s an example SOAP request\n
  • Via uzbeckistan and \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • let’s understand how developers build apps.\n\ndevelopers work in a development cycle (sometimes formally, more often informally) with four 4 phases:\n\nrequirements gathering\ndesign\ndevelopment \nand testing\n\n\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • use facebook as versionless example being bad\n
  • no dots\n\nversion required\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • as they create applications, developers make hundreds or even thousands of simple decisions.\n\nthe faster they make decisions, the faster an app gets made.\n\nthe better the decisions they make, the better the app.\n\nHick’s law states that for simple stimulus-response tasks, the time it takes to make a decision is a function of the number of available options.\n\nThe more options we give our developers about our API the longer it will take them to build apps.\n\nlet’s take a look at an example where unnecessary complexity collides with Hick’s Law.\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • use facebook as versionless example being bad\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • use facebook as versionless example being bad\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • 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

    ×