Designing a REST API

The Idea

REST models a system as addressable resources. The path names a noun, the HTTP method supplies the verb, and the status code carries the outcome. GET is safe and cacheable; PUT and DELETE are idempotent, so a client that retries after a timeout cannot do the work twice.

Real-World Example

A postal address behaves the same way. The address identifies a house; it does not change because you sent a parcel rather than a letter — what you are doing lives in the service you paid for. An endpoint called /createUser welds the verb onto the address, and the address stops being stable.

The Tradeoff

Strict resource modelling makes some operations awkward: a refund or a publish is a verb long before it is a noun, and clients sometimes need three round trips where one custom endpoint would do. Consistency beats purity — choose a convention, version it, and hold the line.

POST   /articles       201 Created   Location: /articles/91
GET    /articles/91    200 OK
PUT    /articles/91    200 OK        (identical result if retried)
DELETE /articles/91    204 No Content
GET    /articles/91    404 Not Found

POST /orders       -> 201 Created, Location: /orders/7
GET  /orders/7     -> 200 OK
___  /orders/7     -> 204 No Content
GET  /orders/7     -> 404 Not Found