This document discusses trends in API design and when it may be appropriate to deviate from trends. It summarizes Netflix's case study in moving away from a RESTful, one-size-fits-all API and instead implementing device-specific APIs. The document also discusses trends around REST, JSON, OAuth, and API versioning and alternatives that may provide more flexibility depending on a system's needs and clients.

1. API Design: When to buck the trend
Netflix API case study with Daniel Jacobson
groups.google.com/group/api-craft
Daniel Jacobson Greg Brail
Netflix Apigee
@daniel_jacobson @gbrail

2. groups.google.com/group/api-craft

3. youtube.com/apigee

4. slideshare.net/apigee

5. http://tinyurl.com/api-strategy-book

6. @daniel_jacobson @gbrail
Daniel Jacobson Greg Brail

7. What’s the trend?
Pragmatic REST style
One size fits all
JSON
OAuth
API versioning in the URI

8. Trend:
PRAGMATIC REST

9. Pragmatic REST – most common style today
URIs are carefully designed
Each URI represents a “resource”
Resource actions are defined by HTTP verbs
GET (read), POST (create), PUT (update), DELETE

10. Pragmatic REST alternatives
Pure REST
Ad-hoc XML / JSON over HTTP
SOAP

11. Alternative: pure REST
Quick definition:
A REST API as defined by Roy Fielding
http://en.wikipedia.org/wiki/REST
and followers
http://martinfowler.com/articles/richardsonMaturityModel.html

12. Alternative: pure REST
Flexible, powerful, and evolvable over decades…
Slow, hard to program, and rare

13. So who cares about REST?
Most APIs that call themselves “REST” are not actually
REST by the pure definition
So pure REST APIs buck the trend. Why?
The server implementation can change URIs
The URI structure is not documented – clients follow
links
So, the server implementation can change the whole
structure of the API
In theory, the API can evolve forever without ever being
“incompatible”

14. Trend:
ONE SIZE FITS ALL

15. One size fits all
Does it make sense to have the same API for all
developers?

16. One size fits all – why yes?
API team can focus on one precise, well-documented API
Reduce training costs across development teams
Can support an unlimited number of known and unknown
developers

17. One size fits all – why not?
Treats all clients generically, so optimized for none
API team becomes bottleneck for UI development

19. One size fits all – why not?
Some of the many client differences:
Memory capacity
Distinct markup types (XML, JSON)
Flat vs. Hierarchical document models
Screen real estate
Document delivery
User interaction models

22. How do you know if your company is ready to consider
alternatives to the one-size-fits-all API model?
Small number of targeted API consumers is the top priority
Very close relationships between these API consumers and the
API team
Increasing divergence of needs across the top priority API
consumers
Strong desire by the API consumers for more optimized
interactions with the API
High value proposition for the API provider to make these API
consumers as effective as possible

23. Netflix’s approach against one-size-fits-all API
Embrace the differences of the devices
Separate content gathering from content formatting
and delivery
Redefine the border between client and server
Distribute innovation

24. Netflix REST API Model
Network Border Network Border
REST API
START- A/B MEMBER RECOMME MOVIE SIMILAR
AUTH NDATIONS
RATINGS
UP TESTS DATA DATA MOVIES

25. Netflix New Non-REST API Model
Network Border Network Border
JAVA API
START- A/B MEMBER RECOMME MOVIE SIMILAR
AUTH NDATIONS
RATINGS
UP TESTS DATA DATA MOVIES

26. Netflix REST API Model
CLIENT CODE
Network Border Network Border
REST API
SERVER CODE
START- A/B MEMBER RECOMME MOVIE SIMILAR
AUTH NDATIONS
RATINGS
UP TESTS DATA DATA MOVIES

27. Netflix New Non-REST API Model
CLIENT CODE
Network Border Network Border
CLIENT ADAPTER CODE
(ON SERVER)
JAVA API
SERVER CODE RECOMME
START- A/B MEMBER NDATIONSA MOVIE SIMILAR
AUTH ZXSXX C
RATINGS
UP TESTS DATA DATA MOVIES
CCC

28. One size fits all – other alternatives
Why not have both?
Layer the different APIs over a common API

29. One size fits all – other alternatives

30. One size fits all – other alternatives
Other alternatives provide greater flexibility
but still have server teams dictate rules
Doesn’t alleviate server team bottleneck issue

31. Trend:
JSON

33. JSON Conventional Wisdom
JSON and XML are exactly the same
JSON is always smaller than XML
JSON is always faster to parse than XML
All clients can parse JSON
All servers can produce JSON

34. JSON considerations
Not all devices support JSON out of the box
Different devices may require different XML schemas
Some devices prefer full document delivery and others
prefer streaming bits
XML and JSON aren’t all that different in size once you
compress them
XML has a different data model than JSON

35. More JSON considerations
There are many more tools built around XML today
than there are built around JSON
XML offers more semantic context than JSON
Saying XML or JSON is not enough – both can support
very different document models

36. JSON advice
Design the guts of the API to separate data gathering
from data formatting
Add a mediation layer (in your code our outside) to
render the right format
If in doubt, support JSON internally, and support
conversion to other formats as a wrapper
JSON -> XML is easier than XML -> JSON

37. Trend:
OAUTH

38. OAuth – super-big trend in APIs
Essential for
APIs that authenticate end users
Unknown (to you) developers
Mobile and native clients

39. OAuth alternatives
Cookies
Netflix’s new approach
Great for apps that are based on browsers
Great if API consumers are very close to API team

40. OAuth alternatives
HTTP Basic Auth + SSL
Two-way SSL
Both are great for server-to-server APIs

41. OAuth alternatives
API keys only
“Two-legged” access when there is no “user”

42. Trend:
API VERSIONING IN URI

43. Versioning
Many APIs include a version number in the
URI (like api.foo.com/v1)
Hostname (v1.api.foo.com)
Query parameter (api.foo.com/v1/bar?version=1)
Content-type header
The version number represents the interface version
The number changes, although rarely

44. Can an API call have NO version?
If you can achieve it, maintenance will be MUCH
simpler
If you cannot, it instills better practices
Reduces lazy programming
Results in fewer versions
Results in a cleaner, less brittle system
And keep in mind, adding new features typically does
not require a new version…
Schematic or structural changes, however, do

45. Average life of a TV: 7-10 years

46. Versioning
1.0
1.5
2.0
3.0?
4.0?
5.0?
Today
2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020

47. Versioning
1.0
1.5
2.0
New API
Today
2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020

48. groups.google.com/group/api-craft

49. THANK YOU
Questions and ideas to:
@gbrail
@daniel_jacobson
groups.google.com/group/api-craft