REST API Design, Part I

Given at PHP Undiscovered, SF.

Transcript

1. RESTFUL API DESIGN
2. Every time someone mentions RESTful web services, there’s always that one person that has to chime in: “That’s not really RESTful, it’s just kinda RESTful.” — Steve Klabnik
3. THE RICHARDSON MATURITY MODEL • Level 0: RPC over HTTP • Level 1: Resources vs. single service endpoint • Level 2: HTTP Verbs vs. URL-based method calls • Level 3: Hypermedia controls
4. BASICALLY, A CONTENT-NEGOTIATED STATE MACHINE
5. <link rel="stylesheet" href="default.css" type="text/css" title="Default Style" />
6. <form method="POST" action="/items"> <input type="text" name="title" /> </form>
7. <link rel="next" href="/next" type="content/type" title="Next!" />
8. MEANINGFUL RESPONSE CODES • 201: Created • 202: We’ll get back to you • 304: Use the copy I gave you last time • 400: WTF URL parameters • 401: Authentication • 403: Access control
9. MEANINGFUL RESPONSE CODES • 406: I refuse to speak XML • 410: Soft deletes • 415: I refuse to listen to XML • 418: Useless, I wanted coffee • 422: Validation failed • 429: Chill out • 451: Legal told me not to • 503: Network/database/dependent service issues
10. SCALE
11. VERSIONING?
12. application/vnd.my-company.app+json; version=2.2 ? X-Version: 2.2 ?
13. INTENTS
14. http://api.fbi.gov/wanted? order_by=notoriety,desc& limit=10& page=1& fields=name,aka,known_associates, reward,description,last_seen vs. http://api.fbi.gov/wanted/most https://mathieu.fenniak.net/stop-designing-fragile-web-apis/