REST API Design, Part II

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