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

18.
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

19.
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

20.
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

21.
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

22.
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

23.
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

24.
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

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

26.
One size fits all – other alternatives

27.
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

28.
Trend:
JSON

29.
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

30.
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

31.
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

32.
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

33.
Trend:
OAUTH

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

35.
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

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

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

38.
Trend:
API VERSIONING IN URI

39.
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

40.
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

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

42.
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

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

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

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