O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

The never-ending REST API design debate -- Devoxx France 2016

1.738 visualizações

Publicada em

Discussion on REST principles, good API design practices, and more.

Publicada em: Internet
  • ➤➤ 3 Reasons Why You Shouldn't take Pills for ED (important) ◆◆◆ http://ishbv.com/rockhardx/pdf
       Responder 
    Tem certeza que deseja  Sim  Não
    Insira sua mensagem aqui
  • ★★ How Long Does She Want You to Last? ★★ A recent study proved that the average man lasts just 2-5 minutes in bed (during intercourse). The study also showed that many women need at least 7-10 minutes of intercourse to reach "The Big O" - and, worse still... 30% of women never get there during intercourse. Clearly, most men are NOT fulfilling there women's needs in bed. Now, as I've said many times - how long you can last is no guarantee of being a GREAT LOVER. But, not being able to last 20, 30 minutes or more, is definitely a sign that you're not going to "set your woman's world on fire" between the sheets. Question is: "What can you do to last longer?" Well, one of the best recommendations I can give you today is to read THIS report. In it, you'll discover a detailed guide to an Ancient Taoist Thrusting Technique that can help any man to last much longer in bed. I can vouch 100% for the technique because my husband has been using it for years :) Here's the link to the report ◆◆◆ http://ishbv.com/rockhardx/pdf
       Responder 
    Tem certeza que deseja  Sim  Não
    Insira sua mensagem aqui

The never-ending REST API design debate -- Devoxx France 2016

  1. 1. The never-ending REST API design debate Guillaume Laforge Restlet — the Web API platform Chair of the Apache Groovy PMC @glaforge
  2. 2. Devoxx Promo Code: ctwdevoxxfr http://www.manning.com/koenig2/ GROOVY IN ACTION 2ND EDITION
  3. 3. We know about APIs! http://restlet.com
  4. 4. We know about APIs! http://restlet.com
  5. 5. ROY FIELDING RESTDISSERTATION
  6. 6. ROY FIELDING RESTDISSERTATION Principled design of the modern Web architecture
  7. 7. 5 Representational State Transfer Architectural properties • Performance • Scalability • Simplicity • Modifiability • Visibility • Portability • Reliability Architectural constraints • Client-server • Stateless • Cacheable • Layered system • Code on demand (optional) • Uniform interface
  8. 8. 6 REST — Uniform interface • Identification of resources • Manipulation of resources 
 through representations • Self-descriptive messages • HATEOAS 
 (Hypermedia AsThe Engine 
 Of Application State)
  9. 9. 6 REST — Uniform interface • Identification of resources • Manipulation of resources 
 through representations • Self-descriptive messages • HATEOAS 
 (Hypermedia AsThe Engine 
 Of Application State) Resource as URIs http://api.co/cars/123
  10. 10. 6 REST — Uniform interface • Identification of resources • Manipulation of resources 
 through representations • Self-descriptive messages • HATEOAS 
 (Hypermedia AsThe Engine 
 Of Application State) Resource as URIs http://api.co/cars/123 JSON, XML…
  11. 11. 6 REST — Uniform interface • Identification of resources • Manipulation of resources 
 through representations • Self-descriptive messages • HATEOAS 
 (Hypermedia AsThe Engine 
 Of Application State) Resource as URIs http://api.co/cars/123 JSON, XML… HTTP GET, POST, PUT, DELETE media types, cacheability…
  12. 12. 6 REST — Uniform interface • Identification of resources • Manipulation of resources 
 through representations • Self-descriptive messages • HATEOAS 
 (Hypermedia AsThe Engine 
 Of Application State) Resource as URIs http://api.co/cars/123 JSON, XML… HTTP GET, POST, PUT, DELETE media types, cacheability… Hypermedia APIs HAL, JSON-LD, Siren…
  13. 13. 7 HTTP methods / URIs for collection/item GET POST PUT DELETE http://api.co/v2/cars/ http://api.co/v2/cars/1234 List all the cars Retrieve an individual car Create a new car Error Replace the entire collection with a whole new list of cars Update an individual car Delete all the cars Delete an individual car
  14. 14. NOUNS ARE GOOD VERBS ARE BAD
  15. 15. 9 Nouns are good, verbs are bad! • Prefer nouns to verbs • nouns refer to resources • resources are handled with HTTP verbs • Verbs can be used for actions or calculations • /login, /logout • /convertTemperature • /repositories/123/star
  16. 16. 11 Singular or plural resources? • Prefer plural forms • /tickets/234 vs /ticket/234 • Avoid confusing odd singular vs plural forms • /person vs /people, or /goose vs /geese • Easier for URL routing (same prefix) • Think of it as: 
 ‘This is the 234th item of the tickets collection’
  17. 17. Camel case?
  18. 18. Camel case? Snake case!
  19. 19. 13 Different casing in the wild • UpperCamelCase or lowerCamelCase • snake_case or dashed-snake-case • Prefer lowercase • Prefer snake_case • Underscores seem more common in APIs • But chose one casing and be consistent!
  20. 20. 14 Dealing with relations in your URLs • /tickets/123/messages/4 • a ticket could be a group of messages • /usergroups/234/users/67 • a user could belong to different usergroups • user should have a URL of its own, referenced from the usergroup payload
  21. 21. API PARAMETERS RULE OF THUMBS
  22. 22. 16 API parameters — rule of thumbs • Path • required, resource identifier • Query • optional, query collections • Body • resource specific logic • Header • global, platform-wide
  23. 23. 17 HTTP Status Code Map http://bit.ly/stcode
  24. 24. 18 Common HTTP status codes • Use appropriate HTTP status codes when answering requests: • 1xx: Hold on… • 2xx: Here you go! • 3xx: Go away! • 4xx:You fucked up :-D • 5xx: I fucked up :-(
  25. 25. 19 Common HTTP Status Codes — 1xx
  26. 26. 20 Common HTTP Status Codes — 2xx
  27. 27. 20 Common HTTP Status Codes — 2xx
  28. 28. 20 Common HTTP Status Codes — 2xx
  29. 29. 20 Common HTTP Status Codes — 2xx
  30. 30. 20 Common HTTP Status Codes — 2xx
  31. 31. 20 Common HTTP Status Codes — 2xx
  32. 32. NOT JUST 200 201 202 204 206
  33. 33. Anti-pattern: returns 200 for everything, even errors!
  34. 34. 23 Not just 200 OK! — 201 Created • Specify a Location header, pointing at the location of the newly created resource POST /cars ... HTTP/1.1 201 Created Location: http://cars.co/v2/cars/5959
  35. 35. API navigation is important to make the API more discoverable
  36. 36. 25 DHC by Restlet: API testing tool
  37. 37. 26 Not just 200 OK! — 202 Accepted • Request accepted but will be handled asynchronously • a job might be running later and yield a result later on POST /jobs ... HTTP/1.1 202 Accepted No payload returned
  38. 38. 27 Not just 200 OK! — 204 No content • The resource was deleted and no payload is returned • but could return 200 OK 
 & provide the payload of the deleted element DELETE /tickets/654 HTTP/1.1 204 No content
  39. 39. 28 Not just 200 OK! — 206 Partial content • A partial list of meteorites is returned, using pagination • add a Link header to facilitate navigation GET /meteorites?page=4 HTTP/1.1 206 Partial content Link: <http://nasa.co/meteorites?page=1>; rel="first", 
 <http://nasa.co/meteorites?page=3>; rel="prev", <http://nasa.co/meteorites?page=5>; rel="next", 
 <http://nasa.co/meteorites?page=9>; rel="last" ...
  40. 40. 29 Not just 200 OK! — 304 Not modified • When HTTP caching headers are in play • the client should have a version in cache already GET /meteorites/654 HTTP/1.1 304 Not modified
  41. 41. Caching!
  42. 42. 31 Last-Modified GET /users/123 Modified-Since: Wed, 13 Apr 2016 02:13:11 GMT HTTP/1.1 200 OK Last-Modified: Fri, 15 Apr 2016 04:58:08 GMT
  43. 43. 32 ETag GET /users/123 If-None-Match: a456ef544eeb7333af HTTP/1.1 200 OK ETag: 686897696a7c876b7e GET /users/123 If-None-Match: 686897696a7c876b7e HTTP/1.1 304 Not modified
  44. 44. PAGINATION
  45. 45. 34 Pagination with query parameters • With a page number: ?page=23 • can also specify a page size • might get odd results when insertions happen • With a cursor: ?cursor=34ea3fd6 • insertion-friendly • With a semantic parameter: ?page=A • interesting when limited / discrete number of pages
  46. 46. 35 Pagination with accept range header • Accept range header not just for bytes GET /users HTTP/1.1 206 Partial content Accept-Ranges: users Content-Range: users 0-9/200 GET /users Range: users=0-9
  47. 47. Wrapped CollectionS
  48. 48. 37 Wrapped collections • Prefer unwrapped collections • unless there’s specific collection payload metadata
 (example: photo album details) • pagination are better in HTTP headers GET /tickets Content-Type: application/json { data: [ { id: 1, ... }, { id: 2, ... } ] } GET /tickets Content-Type: application/json [ { id: 1, ... }, { id: 2, ... } ]
  49. 49. 38 Common HTTP Status Codes — 3xx
  50. 50. 38 Common HTTP Status Codes — 3xx
  51. 51. 38 Common HTTP Status Codes — 3xx
  52. 52. 38 Common HTTP Status Codes — 3xx
  53. 53. 38 Common HTTP Status Codes — 3xx
  54. 54. 38 Common HTTP Status Codes — 3xx
  55. 55. 39 Common HTTP Status Codes — 4xx
  56. 56. 39 Common HTTP Status Codes — 4xx
  57. 57. 39 Common HTTP Status Codes — 4xx
  58. 58. 39 Common HTTP Status Codes — 4xx
  59. 59. 39 Common HTTP Status Codes — 4xx
  60. 60. 39 Common HTTP Status Codes — 4xx
  61. 61. 40 Provide helpful error payloads • No definitive standard yet • http problem proposal and vnd-error mime type HTTP/1.1 403 Forbidden Content-Type: application/problem+json Content-Language: en { "type": "https://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "instance": "/account/12345/msgs/abc", "balance": 30, "accounts": ["/account/12345", "/account/67890"] }
  62. 62. 41 Common HTTP Status Codes — 5xx
  63. 63. 41 Common HTTP Status Codes — 5xx
  64. 64. 41 Common HTTP Status Codes — 5xx
  65. 65. 41 Common HTTP Status Codes — 5xx
  66. 66. 42 Treating unknown status codes • An unknown status code should be treated 
 as the first one of the family • 4xx — 400 generic client error • 5xx — 500 generic server error
  67. 67. RATE LIMITATION
  68. 68. 44 Rate limitation HTTP/1.1 200 OK Date: Mon, 01 Jul 2013 17:27:06 GMT Status: 200 OK X-RateLimit-Limit: 60 X-RateLimit-Remaining: 56 X-RateLimit-Reset: 1372700873 Total number of requests allowed Number of requests left remaining window before the rate limit resets in UTC epoch seconds
  69. 69. ONE SIZE FITS ALL Different payloads for different consumers
  70. 70. 46 Selecting with query parameters • Only 5 stars Chinese restaurants • GET https://api.co/restaurants?type=chinese&stars=5
  71. 71. FILTERING
  72. 72. 48 Filtering • Specify fields you’re interested in: • GET https://api.co/users/123?fields=firstname,lastname,age • Specify excluded fields: • GET https://api.co/users/123?exclude=biography,resume • Specify a « style »: • GET https://api.co/users/123?style=compact
  73. 73. 49 Prefer… the prefer header GET /users/123 HTTP/1.1 Content-Type: application/json Prefer: return=minimal Vary: Prefer,Accept,Accept-Encoding HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Vary: Prefer,Accept,Accept-Encoding Preference-Applied: return=minimal Define different profiles: minimal, mobile, full…
  74. 74. 50 Expanding referenced resources • Use the dot notation to explicit you want sub-resources • GET https://api.co/users/123?fields=address.zip • user • name • address • zip • country • … • …
  75. 75. SORTING
  76. 76. 52 Sorting • SQL-style • GET https://api.co/books?sort=title+DESC • GET https://api.co/books?sort=title+DESC,author+ASC • Sort + asc/desc combo • GET https://api.co/books?sort=title&desc=title • GET https://api.co/books? sort=title,author&desc=title&asc=author
  77. 77. SEARCHING
  78. 78. 54 Searching • Combine various filtering fields • Or provide a full-blown query language
  79. 79. 55 Search / filter / sort… • Also have a look at other approaches • Facebook’s GraphQL • Netflix’s Falcor
  80. 80. v1
  81. 81. 57 Different approaches for API versioning • Most frequent, in the URL: • https://api.com/v2/restaurants/1234 • Custom header: • X-API-Version: 2 • Less frequent, with an accept header • clients don’t have to change endpoint, but update headers GET /restaurants Accept: application/vnd.restaurants.v2+json
  82. 82. hypermedia
  83. 83. 59 Richardson maturity model
  84. 84. 60 Pros & Cons of hypermedia • Pros • more generic clients • can palliate the need for API versioning • Cons • heavier payload (think mobile devices w/ bad connectivity) • clients still need to understand what links are about and how to represent them in their UI
  85. 85. C H A N G E IS U N A V O ID A B L E
  86. 86. 62 Lots of choice • HAL • JSON-LD • Collection+JSON • SIREN • … • Which to chose from? • no real consensus yet • but HAL seems quite common
  87. 87. 63 A word about IDs for linked resources • If you’re tempted to go your own way for hypermedia… • Be sure to define direct links to resources • photos: [http://news.co/articles/123/photos/654,
 http://news.co/articles/123/photos/659] • Not mere IDs for which API clients need to figure out the exact resource location (error-prone) • photos: [654, 659]
  88. 88. 64 Another word about IDs • Usually avoid counter-type IDs: 1, 2, 3, 4… • Prefer UUIDs • makes it harder for malignant users 
 to scan & discover existing resources • auto-incrementing IDs might not be unique 
 in distributed systems
  89. 89. HAL I’m sorry Dave, I can do Hypermedia
  90. 90. 66 HAL approach GET https://api.com/player/1234567890 HTTP/1.1 200 OK { "_links": { "self": { "href": "https://api.com/player/1234567890" }, "friends": { "href": "https://api.com/player/1234567890/friends" } }, "playerId": "1234567890", "name": "Kevin Sookocheff", "alternateName": "soofaloofa", "image": "https://api.com/player/1234567890/avatar.png" } Special _links property
  91. 91. Resources
  92. 92. 68 API design resources • http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api • https://github.com/paypal/api-standards/blob/master/api-style-guide.md • http://blog.octo.com/en/design-a-rest-api/ • https://github.com/interagent/http-api-design/blob/master/SUMMARY.md • http://sookocheff.com/post/api/on-choosing-a-hypermedia-format/ • http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
  93. 93. Thanks for your attention
  94. 94. Questions & Answers

×