API Design - When to buck the trend (Webcast)

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


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

http://en.wikipedia.org/wiki/REST

http://en.wikipedia.org/wiki/REST

http://martinfowler.com/articles/richardsonMaturityModel.html

http://martinfowler.com/articles/richardsonMaturityModel.html

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


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


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)


Netflix New Non-REST API Model

Why not have both?

Layer the different APIs over a common API

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


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


THANK YOUQuestions and ideas to:

@gbrail @daniel_jacobson


Technology

API Design - When to buck the trend (Webcast)