API Design - When to buck the trend (Webcast)

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

http://blog.apigee.com	4462
http://feeds.apigee.com	110
http://blog-dev.wearepropeople.md	74
http://blog.sonoasystems.com	63
http://apigeeblog.localdomain	45
http://blog-dev.apigee.com	38
http://restfulapi.blogspot.com	35
http://blog.edit.apigee.net	10
http://ip54.216-86-157.static.steadfast.net	6
http://ip52.216-86-157.static.steadfast.net	5
http://restfulapi.blogspot.kr	4
http://docs_apigee	4
http://webcache.googleusercontent.com	2
http://restfulapi.blogspot.de	2
http://feeds.feedburner.com	1
http://translate.googleusercontent.com	1
http://www.hanrss.com	1

API Design - When to buck the trend (Webcast)

by Apigee on Jul 24, 2012

Accessibility

Categories

Upload Details

Usage Rights

17 Embeds 4,863

Statistics

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