Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST Best Practices

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.

23365b2ae97212e561fb82442857d8bb?s=128

Keith Casey

October 10, 2015
Tweet

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