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.

Keith Casey

October 10, 2015
Tweet

More Decks by Keith Casey

Other Decks in Programming

Transcript

  1. Who am I? Clarify.io - The API for businesses to

    build apps that Search and Understand their Audio & Videos
  2. • Assumptions • The Origin Story • The Constraints •

    Uniform Interfaces • Additional Resources
  3. • Assumptions • The Origin Story • The Constraints •

    Uniform Interfaces • Additional Resources
  4. Assumptions • APIs are an important part of your job

    • Use them on a regular basis • Potentially build them too • Sometimes public, sometimes private 7
  5. • Assumptions • The Origin Story • The Constraints •

    Uniform Interfaces • Additional Resources
  6. • We had single stack (monolith) applications • Self-contained •

    Completely independent • Built by humans for humans • Promoted duplication of components In the Beginning..
  7. • Web Services • SOAP • XML-RPC • XML over

    HTTP • Other random junk.. A little later..
  8. • Six Constraints • Client-Server • Stateless • Cacheable •

    Layered System • Uniform Interfaces • Code on Demand A little more sanity: REST
  9. What REST is not… 15 • Pretty URLs • XML

    over HTTP • JSON over HTTP
  10. • Assumptions • The Origin Story • The Constraints •

    Uniform Interfaces • Additional Resources
  11. Client-Server • We get this one • By separating them,

    we can vary them • Web & database servers • Scalability & Reliability
  12. Stateless • Each request stands on its own • This

    is where we struggle • Sessions, cookies, etc • Synchronization • Sticky sessions
  13. 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
  14. Cacheable • Within Clarify.io • /v1/bundles/ • GET {limit, iterator,

    embed} • POST {name, media_url, notify_url} • PUT n/a • DELETE n/a
  15. Cacheable • Within Clarify.io • /v1/bundles/{bundle_id} • GET {bundle_id, embed}

    • POST n/a • PUT {name, media_url, notify_url} • DELETE n/a
  16. Layered System • Don’t count on the Client and Server

    communicating directly • We use this on the web every day • Adds silent, invisible dependencies
  17. Layered System - Why? • Allows you to add intermediaries

    • Load balancers, caching • Logging, audit trails • Authentication & Authorization
  18. 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
  19. • Assumptions • The Origin Story • The Constraints •

    Uniform Interfaces • Additional Resources
  20. Uniform Interfaces • Four Principles • Identification of resources •

    Manipulation of resources through these representations • Self-descriptive messages • Hypermedia as the engine of application state (HATEOAS)
  21. Identification of Resources • Generally • /noun/id • /noun/action/id •

    But not required • /?n=noun&id=id • /?n=noun&page=n
  22. 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
  23. Self-Descriptive Messages • Each message should tell you • how

    to process itself; • how to request the next resource; • if that resource is cacheable.
  24. 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
  25. • Assumptions • The Origin Story • The Constraints •

    Uniform Interfaces • Additional Resources