API Design: When to buck the trend and avoid pragmatic REST, one size fits all, JSON, OAuth, and versioning in the URI
•Download as PPTX, PDF•
12 likes•5,636 views
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.
Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Similar to API Design: When to buck the trend and avoid pragmatic REST, one size fits all, JSON, OAuth, and versioning in the URI
Similar to API Design: When to buck the trend and avoid pragmatic REST, one size fits all, JSON, OAuth, and versioning in the URI (20)
More from Apigee | Google Cloud
More from Apigee | Google Cloud (20)
Recently uploaded
Recently uploaded (20)
API Design: When to buck the trend and avoid pragmatic REST, one size fits all, JSON, OAuth, and versioning in the URI
- 1. API Design: When to 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
- 6. @daniel_jacobson @gbrail Daniel Jacobson Greg Brail
- 7. What’s the trend? Pragmatic REST style One size fits all JSON OAuth API versioning in the URI
- 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 Pure REST Ad-hoc XML / JSON over HTTP SOAP
- 11. Alternative: pure REST Quick definition: 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 cares about 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. Trend: ONE SIZE FITS ALL
- 15. One size fits all Does it make sense to have the same API for all developers?
- 16. One size fits all – 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 fits all – why not? Treats all clients generically, so optimized for none API team becomes bottleneck for UI development
- 19. 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
- 22. How do you know 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 against one-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 API Model 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-REST API 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 API Model 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-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 SIMILAR AUTH ZXSXX C RATINGS UP TESTS DATA DATA MOVIES CCC
- 28. One size fits all – other alternatives Why not have both? Layer the different APIs over a common API
- 29. One size fits all – other alternatives
- 30. 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
- 31. Trend: JSON
- 33. JSON Conventional Wisdom 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
- 34. JSON considerations 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
- 35. More 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
- 36. JSON advice 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
- 37. Trend: OAUTH
- 38. OAuth – super-big trend 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 Basic Auth + SSL Two-way SSL Both are great for server-to-server APIs
- 41. OAuth alternatives API keys only “Two-legged” access when there is no “user”
- 42. Trend: API VERSIONING IN URI
- 43. Versioning Many 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 header The version number represents the interface version The number changes, although rarely
- 44. Can an API call 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 of a 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
- 49. THANK YOU Questions and ideas to: @gbrail @daniel_jacobson groups.google.com/group/api-craft