Downloaded 184 times
Uploaded byApigee | Google Cloud
API Design - When to buck the trend (Webcast)
This document discusses trends in API design and when it may be appropriate to deviate from trends. It summarizes Netflix's case study in moving away from a RESTful, one-size-fits-all API and instead implementing device-specific APIs. The document also discusses trends around REST, JSON, OAuth, and API versioning and alternatives that may provide more flexibility depending on a system's needs and clients.
More Related Content
Similar to API Design - When to buck the trend (Webcast)
API Design - When to buck the trend (Webcast)
- 1. API Design: Whento buck the trend Netflix API case study with Daniel Jacobson groups.google.com/group/api-craft Daniel Jacobson Greg Brail Netflix Apigee @daniel_jacobson @gbrail
- 2.
- 3.
- 4.
- 5.
- 6. @daniel_jacobson @gbrail Daniel Jacobson Greg Brail
- 7. What’s the trend? PragmaticREST style One size fits all JSON OAuth API versioning in the URI
- 8.
- 9. Pragmatic REST –most common style today URIs are carefully designed Each URI represents a “resource” Resource actions are defined by HTTP verbs GET (read), POST (create), PUT (update), DELETE
- 10. Pragmatic REST alternatives PureREST Ad-hoc XML / JSON over HTTP SOAP
- 11. Alternative: pure REST Quickdefinition: A REST API as defined by Roy Fielding http://en.wikipedia.org/wiki/REST and followers http://martinfowler.com/articles/richardsonMaturityModel.html
- 12. Alternative: pure REST Flexible,powerful, and evolvable over decades… Slow, hard to program, and rare
- 13. So who caresabout 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 URIs The URI structure is not documented – clients follow links So, the server implementation can change the whole structure of the API In theory, the API can evolve forever without ever being “incompatible”
- 14.
- 15. One size fitsall Does it make sense to have the same API for all developers?
- 16. One size fitsall – why yes? 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
- 17. One size fitsall – why not? Treats all clients generically, so optimized for none API team becomes bottleneck for UI development
- 19. One size fitsall – 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
- 22. How do youknow if your company is ready to consider alternatives to the one-size-fits-all API model? 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
- 23. Netflix’s approach againstone-size-fits-all API Embrace the differences of the devices Separate content gathering from content formatting and delivery Redefine the border between client and server Distribute innovation
- 24. Netflix REST APIModel Network Border Network Border REST API START- A/B MEMBER RECOMME MOVIE SIMILAR AUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
- 25. Netflix New Non-RESTAPI Model Network Border Network Border JAVA API START- A/B MEMBER RECOMME MOVIE SIMILAR AUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
- 26. Netflix REST APIModel CLIENT CODE Network Border Network Border REST API SERVER CODE START- A/B MEMBER RECOMME MOVIE SIMILAR AUTH NDATIONS RATINGS UP TESTS DATA DATA MOVIES
- 27. Netflix New Non-RESTAPI Model CLIENT CODE Network Border Network Border CLIENT ADAPTER CODE (ON SERVER) JAVA API SERVER CODE RECOMME START- A/B MEMBER NDATIONSA MOVIE SIMILAR AUTH ZXSXX C RATINGS UP TESTS DATA DATA MOVIES CCC
- 28. One size fitsall – other alternatives Why not have both? Layer the different APIs over a common API
- 29. One size fitsall – other alternatives
- 30. One size fitsall – other alternatives Other alternatives provide greater flexibility but still have server teams dictate rules Doesn’t alleviate server team bottleneck issue
- 31.
- 33. JSON Conventional Wisdom JSONand 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
- 34. JSON considerations Not alldevices 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
- 35. More JSON considerations Thereare 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
- 36. JSON advice Design theguts 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
- 37.
- 38. OAuth – super-bigtrend in APIs Essential for APIs that authenticate end users Unknown (to you) developers Mobile and native clients
- 39. OAuth alternatives Cookies Netflix’s new approach Great for apps that are based on browsers Great if API consumers are very close to API team
- 40. OAuth alternatives HTTP BasicAuth + SSL Two-way SSL Both are great for server-to-server APIs
- 41. OAuth alternatives API keysonly “Two-legged” access when there is no “user”
- 42.
- 43. Versioning Many APIs includea 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 header The version number represents the interface version The number changes, although rarely
- 44. Can an APIcall have NO version? If you can achieve it, maintenance will be MUCH simpler If you cannot, it instills better practices Reduces lazy programming Results in fewer versions Results 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
- 45. Average life ofa TV: 7-10 years
- 46. Versioning 1.0 1.5 2.0 3.0? 4.0? 5.0? Today 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
- 47. Versioning 1.0 1.5 2.0 New API Today 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020
- 48.
- 49. THANK YOU Questions andideas to: @gbrail @daniel_jacobson groups.google.com/group/api-craft