проектирование REST API: пример кода

Question

Accepted Answer

REST: nouns + HTTP methods, honest status codes, idempotency key on POST, query params for filter/sort/paginate — not RPC verbs in URL.

## Пример

```http
### Create — return 201 with where the new thing lives
POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: 3f9a...   # retry-safe: same key ⇒ server returns the SAME order
{ "items": [{ "sku": "A1", "qty": 2 }] }

HTTP/1.1 201 Created
Location: /api/v1/orders/42
{ "id": 42, "status": "pending", "total": 1998 }
```

```http
### List — filter, sort, paginate via query params (NOT new endpoints)
GET /api/v1/orders?status=paid&sort=-created_at&limit=20&cursor=eyJpZCI6NDJ9

HTTP/1.1 200 OK
Cache-Control: private, max-age=30
{ "data": [ ... ], "next_cursor": "eyJpZCI6NjJ9" }
```

```js
// ❌ RPC-in-a-URL: verbs in the path, everything a POST, 200-with-error bodies
POST /api/getUserOrders   { userId: 7 }        // not cacheable, not discoverable

// ✅ Resource-oriented: nouns + methods + honest status codes
GET  /api/v1/users/7/orders                     // cacheable, obvious, self-describing
```

## Разбор

201 + Location on create; cursor pagination in query; GET cacheable vs POST RPC anti-pattern.

## Итог

REST code demo: resource URLs, proper status codes, idempotency key, query-driven list — not verb soup.