REST Best Practices

(For the record, I hate the phrase "best practices" and prefer "common practices.")

When we discuss APIs, most people immediately think of OAuth, GET and POST, and JSON, few people think of the underlying concepts of nouns and verbs, idempotence, and uniform interfaces. Even less consider how we can combine these concepts into hypermedia to build APIs that are useful, logical, and future-friendly. In this session, we'll combine the basics, explore the larger concepts, and look at the standards that are leading the way.

Transcript

1. REST Best Common Practices D. Keith Casey Jr keith@clarify.io @CaseySoftware
2. Who am I?
3. Who am I? Clarify.io - The API for businesses to build apps that Search and Understand their Audio & Videos
4. Who am I? http://TheAPIDesignBook.com
5. • Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources
6. • Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources
7. Assumptions • APIs are an important part of your job • Use them on a regular basis • Potentially build them too • Sometimes public, sometimes private 7
8. • Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources
9. • We had single stack (monolith) applications • Self-contained • Completely independent • Built by humans for humans • Promoted duplication of components In the Beginning..
10. In the Beginning..
11. • Web Services • SOAP • XML-RPC • XML over HTTP • Other random junk.. A little later..
12. A little later..
13. • Six Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interfaces • Code on Demand A little more sanity: REST
14. “Strictly RESTful” 14 REST is not a Standard.
15. What REST is not… 15 • Pretty URLs • XML over HTTP • JSON over HTTP
16. • Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources
17. Client-Server • We get this one • By separating them, we can vary them • Web & database servers • Scalability & Reliability
18. Stateless • Each request stands on its own • This is where we struggle • Sessions, cookies, etc • Synchronization • Sticky sessions
19. Stateless curl https://api.clarify.io/v1/search? query=dorothy \ --header "Authorization: Bearer myapikey"
20. Stateless - Why? • It’s WEB SCALE • Stability • Reliability • Flexibility
21. Cacheable • GET, PUT, and DELETE should be idempotent or “safe” • The word “safe” here means that if a given HTTP method is invoked 1 or N times, the resource remains the same after the 1st • POST.. stupid POST
22. Cacheable • Within Clarify.io • /v1/bundles/ • GET {limit, iterator, embed} • POST {name, media_url, notify_url} • PUT n/a • DELETE n/a
23. Cacheable • Within Clarify.io • /v1/bundles/{bundle_id} • GET {bundle_id, embed} • POST n/a • PUT {name, media_url, notify_url} • DELETE n/a
24. Layered System • Don’t count on the Client and Server communicating directly • We use this on the web every day • Adds silent, invisible dependencies
25. Layered System - Why? • Allows you to add intermediaries • Load balancers, caching • Logging, audit trails • Authentication & Authorization
26. Skynet Day 26 https://www.twilio.com/engineering/2011/04/22/why-twilio- wasnt-affected-by-todays-aws-issues
27. Code on Demand (optional) • A request doesn’t just retrieve a resource but also the code to act upon it • We don’t have to know or understand the code, just how to run it • Allows for flexibility and upgradability
28. 28 Ummm.. gmail? (or really, any Javascript on the web) Code on Demand (optional)
29. • Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources
30. Uniform Interfaces • Four Principles • Identification of resources • Manipulation of resources through these representations • Self-descriptive messages • Hypermedia as the engine of application state (HATEOAS)
31. Identification of Resources • Generally • /noun/id • /noun/action/id • But not required • /?n=noun&id=id • /?n=noun&page=n
32. Manipulation of Resources • Within Clarify.io • /v1/bundles/ • /v1/bundles/{bundles_id}/insights • /v1/bundles/{bundles_id}/metadata • /v1/bundles/{bundles_id}/tracks • GET, POST, PUT, DELETE
33. Self-Descriptive Messages • Each message should tell you • how to process itself; • how to request the next resource; • if that resource is cacheable.
34. HATEOAS Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g. by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular actions will be available for any particular resources beyond those described in representations previously received from the server. Ref: https://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services
35. • Assumptions • The Origin Story • The Constraints • Uniform Interfaces • Additional Resources
36. No Pun Intended • http://TheAPIDesignBook.com • http://videos.restfest.org • Anything by Mike Amundsen • Anything by Kin Lane
37. D. Keith Casey Jr keith@clarify.io @CaseySoftware REST Best Common Practices
38. Go Buy This! http://TheAPIDesignBook.com