REST API Design, Part I

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/