API Design Antipatterns - APICon SF

710 views

Published on

APIs have become a part of the product ecosystem - and help the businesses by extending their developer base, and offering seamless integration with other services or products. Sometimes, the APIs themselves are the product. However, with so many APIs around, patterns emerge. Patterns are repeatable, reusable solutions to commonly occurring problems. Where there are patterns, there are also antipatterns. While APIs are not a new paradigm - there are no set standards or specifications formed by a committees or governing bodies for APIs. On top of this, the APIs are often built at various stages of the product, and have a good chance of being disjoint as more are added. In this talk Netflix engineers will discuss various antipatterns that creep into the API design and implementation, and how to identify and avoid them. They will also share their experiences with building APIs. While the antipatterns do not pose as big a functional challenge, they can and do impact integration efforts, scalability and performance among other things. After this session, you should be able to get familiar with the best practices around solving the most common patterns, and make your engineers and API consumers happy!

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

  • Be the first to like this

No Downloads
Views
Total views
710
On SlideShare
0
From Embeds
0
Number of Embeds
29
Actions
Shares
0
Downloads
7
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

API Design Antipatterns - APICon SF

  1. 1. API Antipatterns …identifying, and avoiding them Manish Pandit mpandit@netflix.com lobster1234
  2. 2. APIs
  3. 3. APIs A means for software to interact with other software.
  4. 4. Protocol
  5. 5. Protocol – May or may not be standard
  6. 6. Protocol – May or may not be standard – Indicates an agreement between the parties
  7. 7. Payload
  8. 8. Payload Data Format • XML • JSON • Custom Text • Binary…
  9. 9. Payload Transport mechanism • HTTP • SMTP • Custom Text-based • Raw sockets
  10. 10. HTTP Request http
  11. 11. HTTP Request http://www.netflix.com
  12. 12. HTTP Request http://www.netflix.com/header
  13. 13. HTTP Request http://www.netflix.com/header/netflix_logo.gif
  14. 14. HTTP Request http://www.netflix.com/header/netflix_logo.gif Or, getting a resource from the server by giving its location.
  15. 15. Every request has a response.
  16. 16. HTTP Response – Headers • Describing the response
  17. 17. HTTP Response – Headers • Describing the response – Status Code • Indicating the success/failure
  18. 18. HTTP Response – Headers • Describing the response – Status Code • Indicating the success/failure – Body • The data we asked for
  19. 19. REST API REST is not a standard, but an architecture
  20. 20. REST API REST is not a standard, but an architecture, which uses HTTP as a model for all interactions.
  21. 21. REST API • Noun  Resource, or the Entity • Verb  Action
  22. 22. Patterns
  23. 23. Patterns Patterns are re-usable solutions to commonly occurring problems.
  24. 24. Patterns They are identified by humans who write code – the API as well as the client.
  25. 25. Common Scenarios “Getting data from the server”
  26. 26. Common Scenarios “Sending data to the server”
  27. 27. Antipatterns “Antipatterns are re-usable solutions to commonly occurring problems…
  28. 28. Antipatterns ....which look great on the surface but they really aren’t ”
  29. 29. HTTP Response Codes HTTP 200 OK { “success” : false }
  30. 30. HTTP Response Codes HTTP 200 OK { “error” : ”Person abc not found” }
  31. 31. HTTP Response Codes • There are more codes than 200 and 500 – 2xx for success – 3xx for redirects/caching – 4xx for request/client errors – 5xx for server errors
  32. 32. also, the client does not need to see your exception trace…
  33. 33. HTTP Response Codes • Return after a delete? 204 • Failed database constraint? 409 • Method not supported? 405 • Trying to ask for too much data? 413
  34. 34. Query Strings • /pets?name=scruffy
  35. 35. Query Strings • /pets?name=scruffy • /pets/name/scruffy
  36. 36. Query Strings • Avoid query strings for resource identification
  37. 37. Query Strings • Avoid query strings for resource identification • But use them for request metadata
  38. 38. Query Strings • Request Metadata – Pagination – Filtering – Sorting
  39. 39. Query Strings http://some.api.com/movies?start=0&count=10 &sortBy=name&fields=name,cast,releaseDate
  40. 40. Methods • Do not use GET for all reads – HEAD to get headers (mostly used for caching) – OPTIONS • Do not use POST for all writes – POST to create, or upsert – PUT to update – DELETE to delete
  41. 41. Resources vs. Collections A collection holds similar resources – movies – accounts – persons
  42. 42. Resources vs. Collection A path should identify a resource (or resources) in a collection of said resources
  43. 43. Resources vs. Collections • /movies/name/{name} • /users/1234 • /devices/type/bdplayers
  44. 44. Resources vs. Collection Always specify a qualifier in the path when accessing resource(s) in a collection
  45. 45. Resources vs Collection …except when accessing via the primary ID
  46. 46. Resources vs Collection Always think about the path to the resource. /<collection>/<resource identifier>/value And manipulate it with the verbs
  47. 47. Resources Also, the properties of the resource can also be a part of the path. /movies/rating/G
  48. 48. Authentication • 401 Unauthorized
  49. 49. Authentication • 403 Forbidden
  50. 50. Authentication • Use HTTP 401 to indicate that the client needs to authenticate
  51. 51. Authentication • Use HTTP 401 to indicate that the client needs to authenticate • Use HTTP 403 to indicate that the credentials the client holds do not allow access to the said resource(s).
  52. 52. 401 vs 403 401 = Come back with a key 403 = Your key does not work for this lock.
  53. 53. Resources in an Island Every entity or a resource is tied to others.
  54. 54. Resources in an Island When you’re stuck guessing the connections of a resource.
  55. 55. Resources in an Island HATEOAS
  56. 56. Resources in an Island HATEOAS (or something similar)
  57. 57. Resource Discovery Always have your resources discoverable ..via code
  58. 58. Resource Discovery So we talked a lot about discoverability and islands..
  59. 59. Resource Discovery But where do we start?
  60. 60. Resource Discovery Meta pages for resources /<collection>/meta Or </resource>/meta
  61. 61. Async Operations For when synchronous calls just will not work 
  62. 62. Async Operations HTTP 202 – Accepted But…what about the response?
  63. 63. Async Operations Response should help the caller..remember? {“statusUrl”: <some URL>}
  64. 64. Updates vs. Deletes Everything works when there is data..but what when there is no data..?
  65. 65. Updates vs. Deletes HTTP PUT to set a value to null?
  66. 66. Updates vs. Deletes HTTP DELETE to set a value to null? (Remember, we have a path to not just the resource..)
  67. 67. Updates vs. Deletes DELETE /movies/<id>/rating
  68. 68. Data feeds Whats an API that does not syndicate..
  69. 69. Data feeds Think nasty batch jobs sucking the catalog nightly!
  70. 70. Data feeds Request metadata to the rescue?
  71. 71. Data feeds Request metadata to the rescue? ….how about a ?since=1d …or ?since=UTC
  72. 72. State They said REST is stateless…but is it?
  73. 73. State Stateless == Simple
  74. 74. State • State sits only on the server • Requests either change the state, or get it. • All requests see the same state of the resource
  75. 75. State But what about cookies?
  76. 76. State Avoid cookies! • Use tokens instead. Let the client figure out to store it as a cookie for convinience. • Accept cookies as a fallback, but prefer a query parameter or HTTP request header.
  77. 77. More topics.. • Versioning – Using 301s to redirect/retire APIs • Caching – Using HTTP headers correctly – Caching response bodies
  78. 78. RFC 2616
  79. 79. Questions

×