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. REST
    Best Common
    Practices
    D. Keith Casey Jr
    [email protected]
    @CaseySoftware

    View full-size slide

  2. Who am I?
    Clarify.io -
    The API for businesses
    to build apps that
    Search and Understand
    their Audio & Videos

    View full-size slide

  3. Who am I?
    http://TheAPIDesignBook.com

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  6. Assumptions
    • APIs are an important part of your job
    • Use them on a regular basis
    • Potentially build them too
    • Sometimes public, sometimes private
    7

    View full-size slide

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

    View full-size slide

  8. • We had single stack (monolith) applications
    • Self-contained
    • Completely independent
    • Built by humans for humans
    • Promoted duplication of components
    In the Beginning..

    View full-size slide

  9. In the Beginning..

    View full-size slide

  10. • Web Services
    • SOAP
    • XML-RPC
    • XML over HTTP
    • Other random junk..
    A little later..

    View full-size slide

  11. A little later..

    View full-size slide

  12. • Six Constraints
    • Client-Server
    • Stateless
    • Cacheable
    • Layered System
    • Uniform Interfaces
    • Code on Demand
    A little more sanity: REST

    View full-size slide

  13. “Strictly RESTful”
    14
    REST is not a Standard.

    View full-size slide

  14. What REST is not…
    15
    • Pretty URLs
    • XML over HTTP
    • JSON over HTTP

    View full-size slide

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

    View full-size slide

  16. Client-Server
    • We get this one
    • By separating them, we can vary them
    • Web & database servers
    • Scalability & Reliability

    View full-size slide

  17. Stateless
    • Each request stands on its own
    • This is where we struggle
    • Sessions, cookies, etc
    • Synchronization
    • Sticky sessions

    View full-size slide

  18. Stateless
    curl https://api.clarify.io/v1/search?
    query=dorothy \
    --header "Authorization: Bearer myapikey"

    View full-size slide

  19. Stateless - Why?
    • It’s WEB SCALE
    • Stability
    • Reliability
    • Flexibility

    View full-size slide

  20. 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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  23. Layered System
    • Don’t count on the Client and Server
    communicating directly
    • We use this on the web every day
    • Adds silent, invisible dependencies

    View full-size slide

  24. Layered System - Why?
    • Allows you to add intermediaries
    • Load balancers, caching
    • Logging, audit trails
    • Authentication & Authorization

    View full-size slide

  25. Skynet Day
    26
    https://www.twilio.com/engineering/2011/04/22/why-twilio-
    wasnt-affected-by-todays-aws-issues

    View full-size slide

  26. 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

    View full-size slide

  27. 28
    Ummm.. gmail?
    (or really, any Javascript on the web)
    Code on Demand (optional)

    View full-size slide

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

    View full-size slide

  29. Uniform Interfaces
    • Four Principles
    • Identification of resources
    • Manipulation of resources through these
    representations
    • Self-descriptive messages
    • Hypermedia as the engine of application
    state (HATEOAS)

    View full-size slide

  30. Identification of Resources
    • Generally
    • /noun/id
    • /noun/action/id
    • But not required
    • /?n=noun&id=id
    • /?n=noun&page=n

    View full-size slide

  31. 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

    View full-size slide

  32. Self-Descriptive Messages
    • Each message should tell you
    • how to process itself;
    • how to request the next resource;
    • if that resource is cacheable.

    View full-size slide

  33. 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

    View full-size slide

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

    View full-size slide

  35. No Pun Intended
    • http://TheAPIDesignBook.com
    • http://videos.restfest.org
    • Anything by Mike Amundsen
    • Anything by Kin Lane

    View full-size slide

  36. D. Keith Casey Jr
    [email protected]
    @CaseySoftware
    REST Best
    Common Practices

    View full-size slide

  37. Go Buy This!
    http://TheAPIDesignBook.com

    View full-size slide