Best Practices for building HTTP APIs

As presented at Heartland Developer Conference, 2015.

HTTP APIs – or as the brave amongst us choose to call them, REST APIs – are everywhere. If you have been programming any time in the past 5 years or so, you have almost certainly used a HTTP API either directly or indirectly. You may even have built an HTTP API or be about to build one.

Over the years, the dust is still settling on best practices for building HTTP APIs. When is appropriate to use a POST vs. a PUT? When should the different 2xx level status codes be used? What is hypermedia and why should I care? Should I use webhooks? In this talk I will answer these questions and suggest several best practices – including rationale and consequences for each – for building HTTP APIs, covering HTTP methods, status codes, headers, representation formats and structures, linking, and much more!

Transcript

1. BEST PRACTICES FOR BUILDING HTTP APIS Shaunak Kashyap • @shaunak
2. WHY ME? 2007: Yahoo! Tech — first SOA property within Yahoo! 2009: Yahoo! News — backend tech lead 2010: RESTful Web Services Cookbook — peer reviewer 2010: Netflix API team — senior software engineer 2011: Skybox Imaging — team lead for ground systems
3. JSON VS. XML (SPOILER ALERT: USE JSON!) Human-readable Succint Built-in data types No namespaces!
4. P O S T VS. P U T Creation: Does the client know the ID before creation? Yes: Use P U T No: Use P O S T Updates: Use P U T P U T / c o l l e c t i o n / { r e s o u r c e - i d } P O S T / c o l l e c t i o n
5. 2 0 1 C R E A T E D VS. 2 0 2 A C C E P T E D For synchronous creation, use 2 0 1 C r e a t e d For asynchronous operations, Use 2 0 2 A c c e p t e d Clients can poll for status or be notified by server
6. USE 2 0 4 N O C O N T E N T Responses from D E L E T E requests Responses from H E A D requests
7. API EVOLUTION Keep the interface minimal Make changes backwards-compatible Think about forwards compatibility Use (major) versioning sparingly
8. PARTIAL UPDATES G E T / s o m e / r e s o u r c e { " f o o " : " b a r " , " b a z " : " q u x " , / / . . . a d o z e n m o r e p r o p e r t i e s w i t h T O N S o f d a t a . . . } ↓ { " f o o " : " b a r " , " b a z " : [ " b o o " ] , / / . . . a d o z e n m o r e p r o p e r t i e s w i t h T O N S o f d a t a . . . , " h e l l o " : " w o r l d " }
9. JSON-Patch: (RFC 6902) http://jsonpatch.com/ G E T / s o m e / r e s o u r c e { " f o o " : " b a r " , " b a z " : " q u x " , / / . . . a d o z e n m o r e p r o p e r t i e s w i t h T O N S o f d a t a . . . } P A T C H / s o m e / r e s o u r c e C o n t e n t - T y p e : a p p l i c a t i o n / j s o n - p a t c h + j s o n [ { " o p " : " r e p l a c e " , " p a t h " : " / b a z " , " v a l u e " : [ " b o o " ] } , { " o p " : " a d d " , " p a t h " : " / h e l l o " , " v a l u e " : " w o r l d " } ]
10. G E T / s o m e / r e s o u r c e { " f o o " : " b a r " , " b a z " : [ " b o o " ] , / / . . . a d o z e n m o r e p r o p e r t i e s w i t h T O N S o f d a t a . . . , " h e l l o " : " w o r l d " } JSON-Patch has libraries in several languages: http://jsonpatch.com/#libraries
11. CACHING HTTP caching proxies Varnish: Squid: Apache Traffic Server: Use the C a c h e - C o n t r o l header... ... with the s t a l e - w h i l e - r e v a l i d a t e directive Keep your API resources atomic www.varnish-cache.org www.squid-cache.org trafficserver.apache.org C a c h e - C o n t r o l : m a x - a g e = 3 6 0 0 C a c h e - C o n t r o l : m a x - a g e = 3 6 0 0 ; s t a l e - w h i l e - r e v a l i d a t e = 3 0
12. HATEOAS Link relations in JSON — Webhooks HAL
13. CONCURRENCY E T a g & I f - M a t c h headers L a s t - M o d i f i e d & I f - U n m o d i f i e d - S i n c e headers
14. HOME DOCUMENT JSON HOME http://tools.ietf.org/html/draft-nottingham-json-home-02
15. QUESTIONS? Shaunak Kashyap • @shaunak