• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
RESTful API Design, Second Edition
 

RESTful API Design, Second Edition

on

  • 133,538 views

 

Statistics

Views

Total Views
133,538
Views on SlideShare
56,424
Embed Views
77,114

Actions

Likes
328
Downloads
2,218
Comments
12

117 Embeds 77,114

http://blog.apigee.com 41157
http://apigee.com 13570
http://sofish.de 6755
https://blog.apigee.com 4790
http://bcho.tistory.com 3379
http://mobicon.tistory.com 3063
http://www.lovelucy.info 957
http://ds5apn.wordpress.com 563
http://www.redditmedia.com 286
http://www.sultanshakir.com 191
http://alessandroperta.com 185
http://www.ziggytech.net 180
http://blog.naver.com 178
http://blog.sonoasystems.com 150
http://www.sarow.me 144
http://vanilla.aiqingda.com 142
https://mdc-web-tomcat17.ubisoft.org 110
http://bardt.me 91
http://www.sukruuzel.com 86
http://amsdatapp244 65
http://confluence.alm.mentorg.com:8090 55
http://mktg-dev.wearepropeople.md 54
http://wap.aiqingda.com 54
https://twitter.com 52
http://www.kirishikistudios.com 46
http://bucket.pdp.crl.sony.co.jp 45
http://memory-edge.blogspot.co.uk 43
http://play.daumcorp.com 42
http://wiki 40
http://www.qhp-sys.fr 40
http://qiliriver.com 36
http://devel.cz 34
http://www.scoop.it 31
http://confluence.alm.mentorg.com 30
http://localhost 26
http://abtasty.com 26
http://a0.twimg.com 24
http://xianguo.com 23
https://internal.autodesk360beta.com 23
http://sofi.sh 21
https://twimg0-a.akamaihd.net 21
http://translate.googleusercontent.com 19
http://mktg-dev.apigee.com 15
https://si0.twimg.com 15
http://www.hksilicon.com 15
http://us-w1.rockmelt.com 15
http://www.tuicool.com 15
http://feed.sofish.de 14
http://webcache.googleusercontent.com 12
https://memory-edge.blogspot.com 12
More...

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel

110 of 12 previous next Post a comment

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
  • Excellent introduction to REST API design. Thank you!
    Are you sure you want to
    Your message goes here
    Processing…
  • Great explanation on good restful api design. Thank you!
    Are you sure you want to
    Your message goes here
    Processing…
  • Thank you very much. This is a good presentation that sums it very well.
    Are you sure you want to
    Your message goes here
    Processing…
  • @filip26 you're right. i have since dropped the REST label from this content. please confer with my HATEOAS slides here http://www.slideshare.net/apigee/hateoas-101-opinionated-introduction-to-a-rest-api-style
    Are you sure you want to
    Your message goes here
    Processing…
  • Unfortunately this presentation is not about REST but about API based on HTTP. There is lot of misunderstanding. Firstly, REST is architectural style and defines these architectural constraints:
    * uniform interface
    * client-server
    * stateless
    * cache
    * layered system
    Only application that satisfies all constraints is RESTful, (~has REST architecture).

    This presentation is misleading because it shows only some URIs patterns + methods (part of Uniform Interface) and completely misses Hypermedia as the engine of application state (part of Uniform Interface) constraint plus another constrains listed above.

    Maybe that's the reason why R.T.Fielding wrote this:
    - REST APis must be hypertext-driven:
    http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
    and why exists this:
    - Richardson Maturity Model
    http://martinfowler.com/articles/richardsonMaturityModel.html

    Thank you for the effort Apigee, but there is no need for another misleading presentation of REST. The internet is already bloated with similar incorrect articles, presentations, and of course by many APIs claiming that they are RESTful, but they are not in the fact.
    Are you sure you want to
    Your message goes here
    Processing…

110 of 12 previous next

Post Comment
Edit your comment

    RESTful API Design, Second Edition RESTful API Design, Second Edition Presentation Transcript

    • RESTful API DesignSecond EditionBrian Mulloy@landlessness 11.03.11 @ 11:03:11 PSTApigee Dial-in or VoIP@apigee See Details in Chat Window
    • groups.google.com/group/api-craft
    • youtube.com/apigee
    • To be a RESTafarian or a Pragmatist?
    • App App App World of API Internal App APIUser Store Developer APIs Team Systems
    • Application developers are raison dêtre for APIs.
    • Be pragmatic.For the benefit of application developers.
    • Pragmatic RESTful APIs are a design problem.
    • baddesigns.com
    • Paul Mijksenaar Design for Function Award 2011
    • Let’s look at puppies.
    • hackett hacketthackett 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_kevenSmithsonians National Zoo hackett
    • ... .../getAllDogs /getAllLeashedDogs/verifyLocation /verifyVeterinarianLocation/feedNeeded /feedNeededFood/createRecurringWakeUp /createRecurringMedication/giveDirectOrder /doDirectOwnerDiscipline/checkHealth /doExpressCheckupWithVeterinarian/getRecurringWakeUpSchedule /getRecurringFeedingSchedule/getLocation /getHungerLevel/getDog /getSquirrelsChasingPuppies/newDog /newDogForOwner/getNewDogsSince /getNewDogsAtKennelSince/getRedDogs /getRedDogsWithoutSiblings/getSittingDogs /getSittingDogsAtPark/setDogStateTo /setLeashedDogStateTo/replaceSittingDogsWithRunningDogs /replaceParkSittingDogsWithRunningDogs/saveDog /saveMommaDogsPuppies... ...
    • We are on a slippery slope.
    • Keep the simple things simple.
    • Hopkinsii
    • We only need two base URLs per resource.
    • The first is for a collection.
    • /dogs
    • The second is for an element.
    • /dogs/1234
    • POSTGETPUTDELETE
    • CREATEREADUPDATEDELETE
    • Resource POST GET PUT DELETE create read update delete replace create a delete all /dogs list dogs dogs with new dog dogs new dogs if exists treat as a update Bo collection/dogs/1234 show Bo delete Bo create new if not dog in it create Bo Wikipedia
    • Resource POST GET PUT DELETE create read update delete replace create a delete all /dogs list dogs dogs with new dog dogs new dogs treat as a if exists collection update Bo/dogs/1234 create show Bo delete Bo new dog if not in it create Bo Wikipedia
    • Resource POST GET PUT DELETE create read update delete bulk create a delete all /dogs list dogs update new dog dogs dogs if exists update Bo/dogs/1234 error show Bo delete Bo if not error Wikipedia
    • Verbs are bad.
    • Nouns are good.
    • Plurals or singulars?
    • Foursquare/checkinsGroupOn/dealsZappos/Product
    • Plurals are better./dogs
    • Abstract or concrete naming?
    • Super High/thingsHigh/animalsMedium/dogsLow/beagles
    • Concrete is better than abstract./dogs
    • What about associations?
    • GET /owners/5678/dogsPOST /owners/5678/dogs
    • What about complex variations?
    • Cody Simms
    • Sweep variations under the ‘?’
    • /dogs?color=red&state=running&location=park
    • Hopkinsii
    • /dogs
    • What about errors?
    • meredithfarmer
    • 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"}
    • 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”}
    • What about versioning?
    • 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 (partial response)?fields=title,media:group(media:thumbnail)
    • /dogs?fields=name,color,location
    • What about pagination?
    • FacebookoffsetlimitTwitterpagerppLinkedInstartcount
    • /dogs?limit=25&offset=50
    • What about formats?
    • Google Data?alt=jsonFoursquare/venue.jsonDigg*Accept: application/json?type=json* The type argument, if present, overrides the Accept header.
    • /dogs.json/dogs/1234.json
    • What about defaults?
    • FormatjsonPagination (depends on data size)limit=10&offset=0
    • What about attribute names?
    • Twitter"created_at": "Thu Nov 03 05:19:38 +0000 2011"Bing"DateTime": "2011-10-29T09:35:00Z"Foursquare"createdAt": 1320296464
    • JSON is for JavaScript Objectsvar myObject = JSON.parse(response);These looks funny in JavaScripttiming = myObject.created_at;timing = myObject.DateTime;
    • JavaScript Convention"createdAt": 1320296464timing = myObject.createdAt;Medial Capitalization aka CamelCase
    • What about non-resource-y stuff?
    • CalculateTranslateConvert
    • Use verbs not nouns/convert?from=EUR&to=CNY&amount=100
    • What about searching?
    • Global/search?q=fluffy+furScoped/owners/5678/dogs/search?q=fluffy+furFormatted/search.xml?q=fluffy+fur
    • What about counts?
    • /dogs/count
    • What about the rest of the URL?
    • Facebook graph.facebook.com api.facebook.com developers.facebook.comFoursquare api.foursquare.com developers.foursquare.com Twitter api.twitter.com search.twitter.com stream.twitter.com dev.twitter.com
    • API gatewayapi.teachdogrest.comDeveloper connectiondevelopers.teachdogrest.comDo web redirectsapi ! developers (if from browser)dev ! developersdeveloper ! developers
    • What about exceptional stuff?
    • Client intercepts HTTP error codes
    • Twitter/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” : “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}
    • Client supports limited HTTP methods
    • Method Parametercreate/dogs?method=postread/dogsupdate/dogs/1234?method=put&location=parkdelete/dogs/1234?method=delete
    • What about authentication?
    • PayPalPermissions Service APIFacebookOAuth 2.0TwitterOAuth 1.0a
    • Use latest and greatest OAuthOAuth 2.0Don’t do something close, but different.
    • How do application developers use the API?
    • What about chatty applications?
    • First be complete & RESTful.Then provide shortcuts.
    • Partial response syntax can help./owners/5678?fields=name,dogs(name)
    • What about when building an UIrequires a lot of domain knowledge?
    • Complement your API with codelibraries and SDK.
    • Really? All of this? And iterate it?
    • Application API Virtualization LayerAPI API API
    • Be RESTfulOnly 2 URLsNo verbsUse nouns as pluralsConcrete over abstractFor JSON follow JavaScript conventionsSweep complexity behind the ‘?’Borrow from leading APIsAccount for exceptional clientsAdd virtualization layer
    • Questions?
    • THANK YOUSubscribe to API webinars at:youtube.com/apigee
    • THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
    • THANK YOUContact me at:@landlessnessbrian@apigee.com