API Design - When to buck the trend (Webcast)
Upcoming SlideShare
Loading in...5
×
 

API Design - When to buck the trend (Webcast)

on

  • 9,256 views

 

Statistics

Views

Total Views
9,256
Views on SlideShare
3,978
Embed Views
5,278

Actions

Likes
7
Downloads
130
Comments
1

32 Embeds 5,278

http://blog.apigee.com 4462
https://blog.apigee.com 191
http://feeds.apigee.com 110
https://twitter.com 99
http://pages.apigee.com 78
http://blog-dev.wearepropeople.md 74
http://blog.sonoasystems.com 63
http://apigeeblog.localdomain 45
http://restfulapi.blogspot.com 40
http://blog-dev.apigee.com 38
http://restfulapi.blogspot.de 11
http://blog.edit.apigee.net 10
http://restfulapi.blogspot.nl 9
http://ip54.216-86-157.static.steadfast.net 6
http://mysoaone.blogspot.com.au 5
http://ip52.216-86-157.static.steadfast.net 5
http://restfulapi.blogspot.tw 4
http://docs_apigee 4
http://restfulapi.blogspot.kr 4
http://restfulapi.blogspot.com.br 3
http://restfulapi.blogspot.com.au 3
http://restfulapi.blogspot.co.uk 2
http://restfulapi.blogspot.co.at 2
http://webcache.googleusercontent.com 2
http://www.hanrss.com 1
http://restfulapi.blogspot.no 1
http://restfulapi.blogspot.in 1
http://plus.url.google.com 1
http://moderation.local 1
https://web.tweetdeck.com 1
http://feeds.feedburner.com 1
http://translate.googleusercontent.com 1
More...

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

CC Attribution License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
  • <br /><iframe width="350" height="288" src="http://www.youtube.com/embed/StCrm572aEs" frameborder="0"></iframe>
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

API Design - When to buck the trend (Webcast) API Design - When to buck the trend (Webcast) Presentation Transcript

  • 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
  • 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 defined by HTTP verbs GET (read), POST (create), PUT (update), DELETE
  • 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 followers http://martinfowler.com/articles/richardsonMaturityModel.html
  • 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 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”
  • 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 teamsCan support an unlimited number of known and unknowndevelopers
  • One size fits all – why not?Treats all clients generically, so optimized for noneAPI 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
  • 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
  • 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
  • Netflix REST API Model Network Border Network Border REST API START- A/B MEMBER RECOMME MOVIE SIMILARAUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
  • 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
  • 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
  • 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
  • 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 teams dictate rulesDoesn’t alleviate server team bottleneck issue
  • Trend:JSON
  • 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
  • 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
  • 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
  • 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
  • Trend:OAUTH
  • OAuth – super-big trend in APIsEssential for APIs that authenticate end users Unknown (to you) developers Mobile and native clients
  • OAuth alternativesCookies Netflix’s new approach Great for apps that are based on browsers Great if API consumers are very close to API team
  • 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 (api.foo.com/v1/bar?version=1) Content-type headerThe version number represents the interface versionThe number changes, although rarely
  • 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
  • Average life of a TV: 7-10 years
  • 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
  • Versioning 1.0 1.5 2.0 New API Today2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
  • groups.google.com/group/api-craft
  • THANK YOUQuestions and ideas to:@gbrail@daniel_jacobsongroups.google.com/group/api-craft