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.

API Design - 3rd Edition

38,284 views

Published on

Published in: Technology
  • Hello! Get Your Professional Job-Winning Resume Here - Check our website! https://vk.cc/818RFv
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

API Design - 3rd Edition

  1. 1. API Design3rd EditionBrian Mulloy@landlessnessKevin Swiber Apigee@kevinswiber @apigee
  2. 2. groups.google.com/group/api-craft
  3. 3. youtube.com/apigee
  4. 4. slideshare.net/apigee
  5. 5. @landlessness @kevinswiber
  6. 6. “ The real issue is about design: designing things that have the power required for the job while maintaining understandability, the feeling of control, and the pleasure of accomplishment. -Donald Norman
  7. 7. http://www.flickr.com/photos/mattharvey1/5712604622/
  8. 8. Agenda• Recap Previous Edition• API Modeling• Security• Message Design• Hypermedia• Transactions
  9. 9. http://offers.apigee.com/web-api-design-ebook/
  10. 10. URL Design VersioningPlural nouns for /dogs Include version in /v1/dogscollections URLID for entity /dogs/1234 Keep one previous /v1/dogs version long /v2/dogsAssociations /owners/5678/dogs enough for POST GET PUT DELETE developers to4 HTTP migrateMethodsBias toward /dogs (not animals)concrete names ErrorsMultiple /dogs.json 8 Status Codes 200 201 304 400 401 403 404 500formats in URL /dogs.xml Verbose messages {"msg": "verbose, plain language hints"}Paginate with ?limit=10&offset=0limit and offsetQuery params ?color=red&state=running Client ConsiderationsPartial selection ?fields=name,state Client does not ?suppress_response_codes=trueUse medial "createdAt": 1320296464 support HTTPcapitalization myObject.createdAt; status codes /convert?from=EUR&to=CNY&amoun Client does not GET /dogs?method=postUse verbs for GET /dogsnon-resource t=100 support HTTP GET /dogs?method=putrequests methods GET /dogs?method=deleteSearch /search?q=happy%2Blabrador Complement API 1. JavaScript with SDK and code 2. …DNS api.foo.com 3. … developers.foo.com libraries
  11. 11. How do we get started with our API?
  12. 12. Build an API Model http://www.flickr.com/photos/brent_nashville/2156695472/in/photostream/
  13. 13. Don’t Go Cowboy http://www.flickr.com/photos/theory/3364213389/in/photostream/
  14. 14. How do we secure our API?
  15. 15. Twitter Streaming APIAuthorization: Basic aWhlYXJ0OmFwaXM=Amazon Web Services APIAuthorization: AWSAKIAIOSFODNN7EXAMPLE:frJIUNo//yllqDzg=Google APIAuthorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
  16. 16. OAuth2Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
  17. 17. How do approach message design?
  18. 18. Support multiple formats JSON and XML
  19. 19. Make JSON the default
  20. 20. How do we represent single items?
  21. 21. Twitter Foursquare Instagram{ { { "created_at": "Thu Jan 10 08:44:59 "meta": {…}, "meta": {…},+0000 2013", "notifications": […], "data": {} "id": 289291736440791040, "response": {} } "id_str": "289291736440791040", } "text": "@landlessness heres onefor you: 50-year plan to fixDetroitnnhttp://t.co/kJ2l1FZv", "source": "<ahref="http://twitter.com/download/android" rel="nofollow">Twitter forAndroid</a>", "truncated": false, "in_reply_to_status_id": null, "in_reply_to_status_id_str": null, "in_reply_to_user_id": 41020312, "in_reply_to_user_id_str":"41020312", "in_reply_to_screen_name":"landlessness", "user": {…}, "geo": {…}, "coordinates": {…}, "place": {…}, "contributors”:{…}, "retweet_count": 0, "entities": {…}, "favorited": false, "retweeted": false, "possibly_sensitive": false} 21
  22. 22. Twitter Foursquare Instagram{ { { "created_at": "Thu Jan 10 08:44:59 "meta": {…}, "meta": {…},+0000 2013", "notifications": […], "data": { "id": 289291736440791040, "response": { "attribution": {…}, "id_str": "289291736440791040", "checkin": { "type": "image", "text": "@landlessness heres one "id": "50eeff78e4b0f8e9624ea5f8", "location": {…},for you: 50-year plan to fix "createdAt": 1357840248, "comments": {…},Detroitnnhttp://t.co/kJ2l1FZv", "type": "checkin", "filter": "Sierra", "source": "<a "shout": "Pharmacy #DRUGS!!! "created_time": "1357826573",href="http://twitter.com/download/andr #ToothPulled :(", "link":oid" rel="nofollow">Twitter for "timeZone": "America/Detroit", "http://instagr.am/p/UTk5Xut3gN/",Android</a>", "timeZoneOffset": -300, "likes": {…}, "truncated": false, "user": {…}, "images": {…}, "in_reply_to_status_id": null, "venue": {…}, "caption": {…}, "in_reply_to_status_id_str": null, "source": {…} "user_has_liked": false, "in_reply_to_user_id": 41020312, } "id": "365798266911553549_3573549", "in_reply_to_user_id_str": } "user": {…}"41020312", } } "in_reply_to_screen_name": }"landlessness", "user": {…}, "geo": {…}, "coordinates": {…}, "place": {…}, "contributors”:{…}, "retweet_count": 0, "entities": {…}, "favorited": false, "retweeted": false, "possibly_sensitive": false} 22
  23. 23. Take the best of Foursquare and Instagram{ "meta": {…}, "dog": {…} "notifications": […],} 23
  24. 24. How do we represent collections?
  25. 25. Twitter Foursquare Instagram[ { { { "meta": {…}, "meta": {…}, "created_at": "Thu Jan 10 08:44:59 "notifications": […], "data": [+0000 2013", "response": { { "id": 289291736440791040, "recent": [ "attribution": {…}, "id_str": "289291736440791040", { "type": "image", "text": "@landlessness heres one "id": "50eeff78e4b0f8e9624ea5f8", "location": {…},for you: 50-year plan to fix "createdAt": 1357840248, "comments": {…},Detroitnnhttp://t.co/kJ2l1FZv", "type": "checkin", "filter": "Sierra", "source": "<a "shout": "Pharmacy #DRUGS!!! "created_time": "1357826573",href="http://twitter.com/download/andr #ToothPulled :(", "link":oid" rel="nofollow">Twitter for "timeZone": "America/Detroit", "http://instagr.am/p/UTk5Xut3gN/",Android</a>", "timeZoneOffset": -300, "likes": {…}, "truncated": false, "user": {…}, "images": {…}, "in_reply_to_status_id": null, "venue": {…} "caption": {…}, "in_reply_to_status_id_str": null, }, "user_has_liked": false, "in_reply_to_user_id": 41020312, {…}, "id": "365798266911553549_3573549", "in_reply_to_user_id_str": {…}, "user": {…}"41020312", ] }, "in_reply_to_screen_name": } {…},"landlessness", } {…} "user": {…}, ] "geo": {…}, } "coordinates": {…}, } "place": {…}, "contributors”:{…}, "retweet_count": 0, "entities": {…}, "favorited": false, "retweeted": false, "possibly_sensitive": false }, {…}, {…}] 25
  26. 26. Take the best of Foursquare and Instagram{ "meta": {…}, "dogs": {…} /* include same info as single */ "notifications": […],} 26
  27. 27. How do we represent search results?
  28. 28. “ Selecting results is not the same as searching. -Facebook API
  29. 29. Bing Search Google Custom Search Reddit Search{ { { "SearchResponse": { "kind": "customsearch#search", "kind": "Listing", "Version": "2.2", "url": { "data": { "Query": { "type": "application/json", "after": "t3_qy342", "SearchTerms": "sushi" "template": "before": null, }, "https://www.googleapis.com/customsearch/v1?q={s "children": [ "Web": { earchTerms}…}, { "Total": 95200000, "queries": { "data": { "Offset": 0, "request": [ "id": "f605o", "Results": [ { "num_comments": 943, { "title": "Google Custom Search - sushi", "score": 1146, "Title": "The Sushi FAQ - The ultimate "totalResults": "15000000", "ups": 3110,guide to sushi and sashimi and how to ...", "searchTerms": "sushi", "downs": 1964, "Description": "What is sushi?..", "count": 10, "created": 1295553753.0, "Url": "http://www.sushifaq.com/", "startIndex": 1, "url": "CacheUrl": } "http://www.reddit.com/r/AskReddit/comments/f605"http://cc.bingj.com/cache.aspx?q=sushi&d=485519 ] o/this_is_a_long_shot_any_sushi_chefs_need_a_job0808495712&w=yU8fJS-YPT-f4svREMW2xSa75OoBUAZR", }, _in/", "DisplayUrl": "www.sushifaq.com", "context": { "author": "jining", "DateTime": "2013-01-08T15:12:00Z" "title": "Custom Search" } }, }, }, { "searchInformation": { { "Title": "What Is Sushi? - Sushi Guide - "searchTime": 0.314942, "data": {Eatsushi.com", "formattedSearchTime": "0.31", "id": "c9eng”, "Description": "Eatsushi.com...", "totalResults": "15000000", "num_comments": 308, "Url": "formattedTotalResults": "15,000,000" "score": 59,"http://www.eatsushi.com/whatsushi.asp", }, "ups": 128, "CacheUrl": "items": [ "downs": 69,"http://cc.bingj.com/cache.aspx?q=sushi&d=501324 { "created": 1275155900.0,9854931333&w=ihBzI9k9WbrnwxKcV3n8mOoV97M89K-b", "kind": "customsearch#result", "url": "DisplayUrl": "title": "Standardized Usage Statistics "http://www.reddit.com/r/IAmA/comments/c9eng/i_a"www.eatsushi.com/whatsushi.asp", Harvesting Initiative (SUSHI ... - NISO", m_a_sushi_man_ama/", "DateTime": "2013-01-07T13:51:00Z" "htmlTitle": "u003cbu003eStandardized Usage "saved": false, "is_self": true, "permalink": } Statistics Harvesting Initiativeu003c/bu003e "/r/IAmA/comments/c9eng/i_am_a_sushi_man_ama/", ] (u003cbu003eSUSHIu003c/bu003e "author": "IAmASushiMan” } u003cbu003e...u003c/bu003e - NISO", } } "link": }} "http://www.niso.org/workrooms/sushi", ] "displayLink": "www.niso.org", } "snippet": "The Standardized Usage Statistics } Harvesting Initiative (SUSHI) Protocol standard (ANSI/NISO Z39.93-2007) defines an automated request and response model ...”, 29
  30. 30. (Mostly) Follow Google Custom Search{ "meta": { "limit": 1, "offset": 10, "totalResults": 15000000, "query": "sushi", "searchTime": 0.314942 }, "results": [ {}, {}, {} ]} 30
  31. 31. How do we represent links?
  32. 32. Netflix API<link href=“http://api-public.netflix.com/catalog/people/100637” rel=“http://schemas.netflix.com/catalog/person.actor” title="Elijah Wood”></link>GitHub API"organization": { "login": "octocat", "id": 1, "url": "https://api.github.com/users/octocat", "type": "Organization”}
  33. 33. Follow Netflix and the Web Linking spec<link href=“http://api-public.netflix.com/catalog/people/100637” rel=“http://schemas.netflix.com/catalog/person.actor” title="Elijah Wood”></link>
  34. 34. How do we represent actions?
  35. 35. GitHubForm-based API”actions": [{ “name”: “edit-repo”, “method”: “PATCH”, “href”: “https://api.github.com/repos/kevinswiber/siren”, ”fields”: [ { “name”: “name”, “type”: “text” }, { “name”: “description”, “type”: “text” }}]
  36. 36. Form-based API"actions": [{ "name": "edit-repo", “method”: “PATCH”, “href”: “https://api.github.com/repos/kevinswiber/siren”, ”fields”: [ { “name”: “name”, “type”: “text” }, { “name”: “description”, “type”: “text” }}]
  37. 37. How do we represent metadata?
  38. 38. Flickr API (inline)<item type="photo” id="10289” server="2” views="47” faves="0” more="0">Dropbox API (/metadata){ "size": "225.4KB”, "rev": "35e97029684fe”, "bytes": 230783, "modified": "Tue, 19 Jul 2011 21:55:38 +0000”, "path": "/Getting_Started.pdf”, "is_dir": false, "icon": "page_white_acrobat”, "root": "dropbox”, "mime_type": "application/pdf”, "revision": 220823}
  39. 39. Include a metadata in responses and consider a dedicated/meta resource{ "meta": { "size": "225.4KB”, "rev": "35e97029684fe”, "bytes": 230783, "modified": "Tue, 19 Jul 2011 21:55:38 +0000”, "path": "/Getting_Started.pdf”, "is_dir": false, "icon": "page_white_acrobat”, "root": "dropbox”, "mime_type": "application/pdf”, "revision": 220823 }} 39
  40. 40. What can we learn from hypermedia types?
  41. 41. Atom/AtomPub<?xml version="1.0"?><entry xmlns="http://www.w3.org/2005/Atom"> <title>My New Collection</title> <id>urn:uuid:de46e3a1-e489-41a6-88a6-21e7f0e8e2d8</id> <updated>2009-06-12T12:13:46Z</updated> <author> <name>Daffy</name> </author> <summary type="text" /> <content type="application/atom+xml;type=feed" src="http://example.org/my-new-collection"/> <link rel="edit” href="http://example.org/my-new-collection.atom" /></entry>
  42. 42. XHTML<ul class=“search user-list”> <li class=“user”> <div class="avatar"> <a href="/users/@kevin"> <img class=”user-image" src=”/img/avatar.png" /> </a> </div> <div> <a href=“/users/@kevin” rel=“user messages”> <span class=“user-name”>@kevin</span> (<span class="user-text">@kevin</span>) </a> </div> </li></ul>
  43. 43. HAL{ “currentlyProcessing”: 14 “shippedToday”: 20, “_links”: { “self”: { “href”: “/orders?page=2” }, “next”: { “href”: “/orders?page=3” }, “prev”: { “href”: “/orders?page=1” } }}
  44. 44. Collection+JSON{ “collection”: { “version”: “1.0”, “href”: “http://example.org/friends”, “items”: [ “href”: “http://example.org/friends/kevin”, “data”: [ {“name”: “full-name”, “value”: “Kevin Swiber” } ] ], “queries”: [ {“rel”: “search”, “href”: “./search”, “data”: [ {“name”: “search”, “value”: “” } ] }}
  45. 45. Siren{ “class”: [“owner”, “vip”], “properties”: { “name”: “Kevin” }, “entities”: [ { “rel”: [“https://rels.x.io/dog”], “href”: “https://api.x.io/dogs/1” } ], “actions”: [ { “name”: “adopt”, “method”: “POST”, “href”: “https://api.x.io/owners/1/dogs”, “fields”: [ { “name”: “dog-name”, “type”: “text” } ] } ], “links”: [ { “rel”: [“self”], “href”: “https://api.x.io/owners/1” } ]}
  46. 46. How do we accept binary data?
  47. 47. multipart/form-dataContent-Type: multipart/form-data; boundary=AaB03x--AaB03xContent-Disposition: form-data; name=“caption”Cool picture of my cat.--AaB03xContent-Disposition: form-data; name=“photo”; filename=“catpajamas.jpg”Content-Type: image/jpegContent-Transfer-Encoding: binary…contents of catpajamas.jpg…--AaB03x
  48. 48. Inline Base64 EncodingPOST /photos{ “caption”: “Cool picture of my cat.” “photo”: “RHVkZSwgbXkgY2F0IGhhcyB0aGUgYmVzdCBwYWphbWFzLg==”}
  49. 49. 2-Step ProcessPOST /photos{ “caption”: “Cool picture of my cat.”}PUT /photos/1234/dataContent-Type: image/jpegContent-Length: 240Content-Transfer-Encoding: binary…binary content…
  50. 50. Opt for multipart/form-data.Be consistent.
  51. 51. How do we support caching?
  52. 52. Expiration200 OKCache-Control: private, max-age=2592000
  53. 53. ETagsGET /dogs/1ETag: “a7D92kda94aisdfG”GET /dogs/1If-None-Match: “a7D92kda94aisdfG”
  54. 54. Last-ModifiedGET /dogs/1Last-Modified: Thu, 10 Jan 2013 19:43:31 GMTGET /dogs/1If-Modified-Since: Thu, 10 Jan 2013 19:43:31 GMT
  55. 55. Think about the client.
  56. 56. Do we need a JavaScript API?
  57. 57. Yes. Follow LinkedIn’s lead.
  58. 58. What about posting data?
  59. 59. application/x-www-form-urlencoded breed=Dachshund&name=Hotdog&age=2
  60. 60. application/xml<dog> <breed>Dachshund</breed> <name>Hotdog</name> <age>2</age></dog>
  61. 61. application/json { “breed”: “Dachshund”, “name”: “Hotdog”, “age”: 2 }
  62. 62. Favor application/x-www-form-urlencoded data.
  63. 63. How do we handle transactions?
  64. 64. Create a TransactionPOST /carts…201 CreatedLocation: /carts/1
  65. 65. Add ItemsPOST /carts/1/items/{ “productId”: “mittens123”, “quantity”: 1 }…201 CreatedLocation: /cartItems/1234
  66. 66. Commit the TransactionPOST /carts/1{ “message”: “checkout” }…200 OK
  67. 67. Summary• Checkout previous editions for URI design• Start with API modeling• Use OAuth for security• Good message design is for developers• Learn from hypermedia specs• More on transactions later
  68. 68. Questions?
  69. 69. THANK YOUSubscribe to API webinars at:youtube.com/apigee
  70. 70. THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
  71. 71. THANK YOUContact us at:@landlessnessbrian@apigee.com@kevinswiberkswiber@apigee.com@apigee

×