REST API Design, Part I

REST API Design, Part I

Given at PHP Undiscovered, SF.

7fca546408cc6d46ab158f06baed2535?s=128

Nate Abele

August 29, 2013
Tweet

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/