API Design: When to buck the trendNetflix API case study with Daniel Jacobsongroups.google.com/group/api-craftDaniel Jacob...
groups.google.com/group/api-craft
youtube.com/apigee
slideshare.net/apigee
http://tinyurl.com/api-strategy-book
@daniel_jacobson    @gbrail Daniel Jacobson   Greg Brail
What’s the trend?Pragmatic REST styleOne size fits allJSONOAuthAPI versioning in the URI
Trend:PRAGMATIC REST
Pragmatic REST – most common style todayURIs are carefully designedEach URI represents a “resource”Resource actions are de...
Pragmatic REST alternativesPure RESTAd-hoc XML / JSON over HTTPSOAP
Alternative: pure RESTQuick definition:  A REST API as defined by Roy Fielding  http://en.wikipedia.org/wiki/REST  and fol...
Alternative: pure RESTFlexible, powerful, and evolvable over decades…Slow, hard to program, and rare
So who cares about REST?Most APIs that call themselves “REST” are not actuallyREST by the pure definitionSo pure REST APIs...
Trend:ONE SIZE FITS ALL
One size fits allDoes it make sense to have the same API for alldevelopers?
One size fits all – why yes?API team can focus on one precise, well-documented APIReduce training costs across development...
One size fits all – why not?Treats all clients generically, so optimized for noneAPI team becomes bottleneck for UI develo...
One size fits all – why not?Some of the many client differences:   Memory capacity   Distinct markup types (XML, JSON)   F...
How do you know if your company is ready to consideralternatives to the one-size-fits-all API model?Small number of target...
Netflix’s approach against one-size-fits-all APIEmbrace the differences of the devicesSeparate content gathering from cont...
Netflix REST API Model Network Border                                        Network Border                              R...
Netflix New Non-REST API Model Network Border                                       Network Border                        ...
Netflix REST API Model                   CLIENT CODE Network Border                                       Network Border  ...
Netflix New Non-REST API Model                     CLIENT CODE Network Border                                           Ne...
One size fits all – other alternativesWhy not have both?Layer the different APIs over a common API
One size fits all – other alternatives
One size fits all – other alternativesOther alternatives provide greater flexibility            but still have server team...
Trend:JSON
JSON Conventional WisdomJSON and XML are exactly the sameJSON is always smaller than XMLJSON is always faster to parse tha...
JSON considerationsNot all devices support JSON out of the boxDifferent devices may require different XML schemasSome devi...
More JSON considerationsThere are many more tools built around XML todaythan there are built around JSONXML offers more se...
JSON adviceDesign the guts of the API to separate data gatheringfrom data formattingAdd a mediation layer (in your code ou...
Trend:OAUTH
OAuth – super-big trend in APIsEssential for  APIs that authenticate end users  Unknown (to you) developers  Mobile and na...
OAuth alternativesCookies  Netflix’s new approach  Great for apps that are based on browsers  Great if API consumers are v...
OAuth alternativesHTTP Basic Auth + SSLTwo-way SSL  Both are great for server-to-server APIs
OAuth alternativesAPI keys only  “Two-legged” access when there is no “user”
Trend:API VERSIONING IN URI
VersioningMany APIs include a version number in the  URI (like api.foo.com/v1)  Hostname (v1.api.foo.com)  Query parameter...
Can an API call have NO version?If you can achieve it, maintenance will be MUCHsimplerIf you cannot, it instills better pr...
Average life of a TV: 7-10 years
Versioning                                    1.0                                      1.5                                ...
Versioning                                    1.0                                      1.5                                ...
groups.google.com/group/api-craft
THANK YOUQuestions and ideas to:@gbrail@daniel_jacobsongroups.google.com/group/api-craft
API Design - When to buck the trend (Webcast)
API Design - When to buck the trend (Webcast)
API Design - When to buck the trend (Webcast)
API Design - When to buck the trend (Webcast)
Upcoming SlideShare
Loading in...5
×

API Design - When to buck the trend (Webcast)

9,215

Published on

Published in: Technology
1 Comment
7 Likes
Statistics
Notes
  • <br /><iframe width="350" height="288" src="http://www.youtube.com/embed/StCrm572aEs" frameborder="0"></iframe>
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total Views
9,215
On Slideshare
0
From Embeds
0
Number of Embeds
15
Actions
Shares
0
Downloads
153
Comments
1
Likes
7
Embeds 0
No embeds

No notes for slide

API Design - When to buck the trend (Webcast)

  1. 1. API Design: When to buck the trendNetflix API case study with Daniel Jacobsongroups.google.com/group/api-craftDaniel Jacobson Greg BrailNetflix Apigee@daniel_jacobson @gbrail
  2. 2. groups.google.com/group/api-craft
  3. 3. youtube.com/apigee
  4. 4. slideshare.net/apigee
  5. 5. http://tinyurl.com/api-strategy-book
  6. 6. @daniel_jacobson @gbrail Daniel Jacobson Greg Brail
  7. 7. What’s the trend?Pragmatic REST styleOne size fits allJSONOAuthAPI versioning in the URI
  8. 8. Trend:PRAGMATIC REST
  9. 9. Pragmatic REST – most common style todayURIs are carefully designedEach URI represents a “resource”Resource actions are defined by HTTP verbs GET (read), POST (create), PUT (update), DELETE
  10. 10. Pragmatic REST alternativesPure RESTAd-hoc XML / JSON over HTTPSOAP
  11. 11. Alternative: pure RESTQuick definition: A REST API as defined by Roy Fielding http://en.wikipedia.org/wiki/REST and followers http://martinfowler.com/articles/richardsonMaturityModel.html
  12. 12. Alternative: pure RESTFlexible, powerful, and evolvable over decades…Slow, hard to program, and rare
  13. 13. So who cares about REST?Most APIs that call themselves “REST” are not actuallyREST by the pure definitionSo 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 APIIn theory, the API can evolve forever without ever being“incompatible”
  14. 14. Trend:ONE SIZE FITS ALL
  15. 15. One size fits allDoes it make sense to have the same API for alldevelopers?
  16. 16. One size fits all – why yes?API team can focus on one precise, well-documented APIReduce training costs across development teamsCan support an unlimited number of known and unknowndevelopers
  17. 17. One size fits all – why not?Treats all clients generically, so optimized for noneAPI team becomes bottleneck for UI development
  18. 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. 19. How do you know if your company is ready to consideralternatives to the one-size-fits-all API model?Small number of targeted API consumers is the top priorityVery close relationships between these API consumers and theAPI teamIncreasing divergence of needs across the top priority APIconsumersStrong desire by the API consumers for more optimizedinteractions with the APIHigh value proposition for the API provider to make these APIconsumers as effective as possible
  20. 20. Netflix’s approach against one-size-fits-all APIEmbrace the differences of the devicesSeparate content gathering from content formattingand deliveryRedefine the border between client and serverDistribute innovation
  21. 21. Netflix REST API Model Network Border Network Border REST API START- A/B MEMBER RECOMME MOVIE SIMILARAUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
  22. 22. Netflix New Non-REST API Model Network Border Network Border JAVA API START- A/B MEMBER RECOMME MOVIE SIMILARAUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
  23. 23. Netflix REST API Model CLIENT CODE Network Border Network Border REST API SERVER CODE START- A/B MEMBER RECOMME MOVIE SIMILARAUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
  24. 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 SIMILARAUTH ZXSXX C RATINGS UP TESTS DATA DATA MOVIES CCC
  25. 25. One size fits all – other alternativesWhy not have both?Layer the different APIs over a common API
  26. 26. One size fits all – other alternatives
  27. 27. One size fits all – other alternativesOther alternatives provide greater flexibility but still have server teams dictate rulesDoesn’t alleviate server team bottleneck issue
  28. 28. Trend:JSON
  29. 29. JSON Conventional WisdomJSON and XML are exactly the sameJSON is always smaller than XMLJSON is always faster to parse than XMLAll clients can parse JSONAll servers can produce JSON
  30. 30. JSON considerationsNot all devices support JSON out of the boxDifferent devices may require different XML schemasSome devices prefer full document delivery and othersprefer streaming bitsXML and JSON aren’t all that different in size once youcompress themXML has a different data model than JSON
  31. 31. More JSON considerationsThere are many more tools built around XML todaythan there are built around JSONXML offers more semantic context than JSONSaying XML or JSON is not enough – both can supportvery different document models
  32. 32. JSON adviceDesign the guts of the API to separate data gatheringfrom data formattingAdd a mediation layer (in your code our outside) torender the right formatIf in doubt, support JSON internally, and supportconversion to other formats as a wrapper JSON -> XML is easier than XML -> JSON
  33. 33. Trend:OAUTH
  34. 34. OAuth – super-big trend in APIsEssential for APIs that authenticate end users Unknown (to you) developers Mobile and native clients
  35. 35. OAuth alternativesCookies Netflix’s new approach Great for apps that are based on browsers Great if API consumers are very close to API team
  36. 36. OAuth alternativesHTTP Basic Auth + SSLTwo-way SSL Both are great for server-to-server APIs
  37. 37. OAuth alternativesAPI keys only “Two-legged” access when there is no “user”
  38. 38. Trend:API VERSIONING IN URI
  39. 39. VersioningMany 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 headerThe version number represents the interface versionThe number changes, although rarely
  40. 40. Can an API call have NO version?If you can achieve it, maintenance will be MUCHsimplerIf you cannot, it instills better practices Reduces lazy programming Results in fewer versions Results in a cleaner, less brittle systemAnd keep in mind, adding new features typically doesnot require a new version… Schematic or structural changes, however, do
  41. 41. Average life of a TV: 7-10 years
  42. 42. Versioning 1.0 1.5 2.0 3.0? 4.0? 5.0? Today2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
  43. 43. Versioning 1.0 1.5 2.0 New API Today2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
  44. 44. groups.google.com/group/api-craft
  45. 45. THANK YOUQuestions and ideas to:@gbrail@daniel_jacobsongroups.google.com/group/api-craft

×