REST API Design, Part II

REST API Design, Part II

Given at PHP Undiscovered, SF.

7fca546408cc6d46ab158f06baed2535?s=128

Nate Abele

August 30, 2013
Tweet

Transcript

  1. The Dream of the 90’s is Withering on the Vine

    (in Portland)
  2. How to Future-Proof & Increase The Level of Sanity in

    the Design of Your APIs, by Respecting the Best Practices of HTTP Or...
  3. This is Roy

  4. Principles • Client-Server • Stateless • Cacheable • Uniform Interface

    • Opaque Layering • Code-on-Demand
  5. Objectives •Auth •Querying •Relationships •Pagination •Formats •Caching •Logging •API Versioning

  6. Auth •Simple! •Basic vs. Digest (over SSL, obviously) •Upshot of

    Basic: http://user:pass@my.api/objects •Cookies? •Custom Tokens?
  7. Querying •There are approaches to making this discoverable •They are

    ridiculously ivory-tower •Better: ?q=<whatever>
  8. Relationships •Goal: Introspect API domain model and transform object relationships

    to URLs
  9. Relationships GET /tasks HTTP/1.1 [{ title: "Finish client demo", completed:

    false, _links: { self: { href: "http://my.app/tasks/1138" }, owner: { href: "http://my.app/users/nate" }, subtasks: { href: "http://my.app/tasks/1138/subtasks" } } }]
  10. Pagination GET /tasks?page=5&order=due ?

  11. Pagination HTTP Range! GET /videos/rickroll.mp4 Range: bytes=100-99999

  12. Pagination HEAD /tasks HTTP/1.1 ... HTTP 200 OK Accept-Ranges: tasks

  13. Pagination HEAD /posts HTTP/1.1 ... HTTP 200 OK Accept-Ranges: posts

  14. Pagination GET /posts HTTP/1.1 Range: posts=1-20

  15. Caching (Strategies) • Generated cache keys (ETag, If-None-Match) • For

    writes: If-Match • Time-based (Last-Modified / If-Modified-Since)
  16. Logging Custom Response Headers!

  17. Logging X-Query-Log: SELECT * From users WHERE name = "nate"

    X-Query-Log: SELECT * From tasks WHERE user_id = 13
  18. Logging X-Query-Log: users.find({ name: "nate" })

  19. DEMO