api design - when to buck the trend (webcast)
DESCRIPTION
TRANSCRIPT
API Design: When to buck the trend
Netflix API case study with Daniel Jacobson
Daniel JacobsonNetflix@daniel_jacobson
groups.google.com/group/api-craft
Greg BrailApigee@gbrail
groups.google.com/group/api-craft
youtube.com/apigee
slideshare.net/apigee
http://tinyurl.com/api-strategy-book
@daniel_jacobsonDaniel Jacobson
@gbrailGreg Brail
Pragmatic REST style
One size fits all
JSON
OAuth
API versioning in the URI
What’s the trend?
Trend:PRAGMATIC REST
URIs are carefully designed
Each URI represents a “resource”
Resource actions are defined by HTTP verbs
GET (read), POST (create), PUT (update), DELETE
Pragmatic REST – most common style today
Pure REST
Ad-hoc XML / JSON over HTTP
SOAP
Pragmatic REST alternatives
Quick definition:
A REST API as defined by Roy Fieldinghttp://en.wikipedia.org/wiki/RESTand followershttp://martinfowler.com/articles/richardsonMaturityModel.html
Alternative: pure REST
Flexible, powerful, and evolvable over decades…
Slow, hard to program, and rare
Alternative: pure 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 URIsThe URI structure is not documented – clients follow linksSo, the server implementation can change the whole structure of the API
In theory, the API can evolve forever without ever being “incompatible”
So who cares about REST?
Trend:ONE SIZE FITS ALL
Does it make sense to have the same API for all developers?
One size fits all
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
One size fits all – why yes?
Treats all clients generically, so optimized for none
API team becomes bottleneck for UI development
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
One size fits all – why not?
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
How do you know if your company is ready to consider alternatives to the one-size-fits-all API model?
Embrace the differences of the devices
Separate content gathering from content formatting and delivery
Redefine the border between client and server
Distribute innovation
Netflix’s approach against one-size-fits-all API
REST API
RECOMMENDATIONS
MOVIE DATA
SIMILAR MOVIES
AUTH MEMBERDATA
A/B TESTS
START-UP
RATINGS
Network Border Network Border
Netflix REST API Model
JAVA API
Network Border Network Border
RECOMMENDATIONS
MOVIE DATA
SIMILAR MOVIES
AUTH MEMBERDATA
A/B TESTS
START-UP
RATINGS
Netflix New Non-REST API Model
RECOMMENDATIONS
MOVIE DATA
SIMILAR MOVIES
AUTH MEMBERDATA
A/B TESTS
START-UP
RATINGS
REST API
Network Border Network Border
SERVER CODE
CLIENT CODE
Netflix REST API Model
RECOMMENDATIONSA
ZXSXX C CCC
MOVIE DATA
SIMILAR MOVIES
AUTH MEMBERDATA
A/B TESTS
START-UP
RATINGS
JAVA API
SERVER CODE
CLIENT CODE
CLIENT ADAPTER CODE(ON SERVER)
Network Border Network Border
Netflix New Non-REST API Model
Why not have both?
Layer the different APIs over a common API
One size fits all – other alternatives
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
One size fits all – other alternatives
Trend:JSON
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
JSON Conventional Wisdom
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
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
More JSON considerations
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
JSON advice
Trend:OAUTH
Essential for
APIs that authenticate end users
Unknown (to you) developers
Mobile and native clients
OAuth – super-big trend in APIs
Cookies
Netflix’s new approach
Great for apps that are based on browsers
Great if API consumers are very close to API team
OAuth alternatives
HTTP Basic Auth + SSLTwo-way SSL
Both are great for server-to-server APIs
OAuth alternatives
API keys only
“Two-legged” access when there is no “user”
OAuth alternatives
Trend:API VERSIONING IN URI
Many APIs include a version number in theURI (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
Versioning
If you can achieve it, maintenance will be MUCH simpler
If you cannot, it instills better practicesReduces lazy programmingResults in fewer versionsResults 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
Can an API call have NO version?
Average life of a TV: 7-10 years
1.0
1.5
2.0
Today
3.0?
4.0?
5.0?
2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
Versioning
1.0
1.5
2.0
New API
Today
2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
Versioning
groups.google.com/group/api-craft
THANK YOUQuestions and ideas to:
@gbrail @daniel_jacobson
groups.google.com/group/api-craft