REST API Design, Part I

Slide 1

Slide 1 text

RESTFUL API DESIGN

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

BASICALLY, A CONTENT-NEGOTIATED STATE MACHINE

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

SCALE

Slide 11

Slide 11 text

VERSIONING?

Slide 12

Slide 12 text

application/vnd.my-company.app+json; version=2.2 ? X-Version: 2.2 ?

Slide 13

Slide 13 text

INTENTS

Slide 14

Slide 14 text

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/