REST API Design, Part II

Given at PHP Undiscovered, SF.

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