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!

1. API Antipatterns
…identifying, and avoiding them
Manish Pandit
mpandit@netflix.com
lobster1234

2. APIs

3. APIs
A means for software to interact with other
software.

4. Protocol

5. Protocol
– May or may not be standard

6. Protocol
– May or may not be standard
– Indicates an agreement between the parties

7. Payload

8. Payload
Data Format
• XML
• JSON
• Custom Text
• Binary…

9. Payload
Transport mechanism
• HTTP
• SMTP
• Custom Text-based
• Raw sockets

10. HTTP Request
http

11. HTTP Request
http://www.netflix.com

12. HTTP Request
http://www.netflix.com/header

13. HTTP Request
http://www.netflix.com/header/netflix_logo.gif

14. HTTP Request
http://www.netflix.com/header/netflix_logo.gif
Or, getting a resource from the server by giving
its location.

15. Every request has a response.

16. HTTP Response
– Headers
• Describing the response

17. HTTP Response
– Headers
• Describing the response
– Status Code
• Indicating the success/failure

18. HTTP Response
– Headers
• Describing the response
– Status Code
• Indicating the success/failure
– Body
• The data we asked for

19. REST API
REST is not a standard, but an architecture

20. REST API
REST is not a standard, but an architecture,
which uses HTTP as a model for all interactions.

21. REST API
• Noun  Resource, or the Entity
• Verb  Action

22. Patterns

23. Patterns
Patterns are re-usable solutions to commonly occurring problems.

24. Patterns
They are identified by humans who write code – the API as well as the client.

25. Common Scenarios
“Getting data from the server”

26. Common Scenarios
“Sending data to the server”

27. Antipatterns
“Antipatterns are re-usable solutions to
commonly occurring problems…

28. Antipatterns
....which look great on the surface but they
really aren’t ”

29. HTTP Response Codes
HTTP 200 OK
{ “success” : false }

30. HTTP Response Codes
HTTP 200 OK
{ “error” : ”Person abc not found” }

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. also, the client does not need to see your exception
trace…

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. Query Strings
• /pets?name=scruffy

35. Query Strings
• /pets?name=scruffy
• /pets/name/scruffy

36. Query Strings
• Avoid query strings for resource identification

37. Query Strings
• Avoid query strings for resource identification
• But use them for request metadata

38. Query Strings
• Request Metadata
– Pagination
– Filtering
– Sorting

39. Query Strings
http://some.api.com/movies?start=0&count=10
&sortBy=name&fields=name,cast,releaseDate

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. Resources vs. Collections
A collection holds similar resources
– movies
– accounts
– persons

42. Resources vs. Collection
A path should identify a resource (or resources)
in a collection of said resources

43. Resources vs. Collections
• /movies/name/{name}
• /users/1234
• /devices/type/bdplayers

44. Resources vs. Collection
Always specify a qualifier in the path when
accessing resource(s) in a collection

45. Resources vs Collection
…except when accessing via the primary ID

46. Resources vs Collection
Always think about the path to the resource.
/<collection>/<resource identifier>/value
And manipulate it with the verbs

47. Resources
Also, the properties of the resource can also be
a part of the path.
/movies/rating/G

48. Authentication
• 401 Unauthorized

49. Authentication
• 403 Forbidden

50. Authentication
• Use HTTP 401 to indicate that the client needs
to authenticate

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. 401 vs 403
401 = Come back with a key
403 = Your key does not work for this lock.

53. Resources in an Island
Every entity or a resource is tied to others.

54. Resources in an Island
When you’re stuck guessing the connections of
a resource.

55. Resources in an Island
HATEOAS

56. Resources in an Island
HATEOAS
(or something similar)

57. Resource Discovery
Always have your resources discoverable
..via code

58. Resource Discovery
So we talked a lot about discoverability and
islands..

59. Resource Discovery
But where do we start?

60. Resource Discovery
Meta pages for resources
/<collection>/meta
Or
</resource>/meta

61. Async Operations
For when synchronous calls just will not work 

62. Async Operations
HTTP 202 – Accepted
But…what about the response?

63. Async Operations
Response should help the caller..remember?
{“statusUrl”: <some URL>}

64. Updates vs. Deletes
Everything works when there is data..but what
when there is no data..?

65. Updates vs. Deletes
HTTP PUT to set a value to null?

66. Updates vs. Deletes
HTTP DELETE to set a value to null?
(Remember, we have a path to not just the
resource..)

67. Updates vs. Deletes
DELETE /movies/<id>/rating

68. Data feeds
Whats an API that does not syndicate..

69. Data feeds
Think nasty batch jobs sucking the catalog
nightly!

70. Data feeds
Request metadata to the rescue?

71. Data feeds
Request metadata to the rescue?
….how about a ?since=1d
…or ?since=UTC

72. State
They said REST is stateless…but is it?

73. State
Stateless == Simple

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. State
But what about cookies?

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. More topics..
• Versioning
– Using 301s to redirect/retire APIs
• Caching
– Using HTTP headers correctly
– Caching response bodies

78. RFC 2616

79. Questions