Know-How
REST API Design Best Practices
Dobře navržené REST API je intuitivní, konzistentní a snadno použitelné. Špatně navržené API je noční můra.
URL konvence
# ✅ Správně
GET /api/v1/users # List
GET /api/v1/users/123 # Detail
POST /api/v1/users # Create
PUT /api/v1/users/123 # Update (celý)
PATCH /api/v1/users/123 # Update (částečný)
DELETE /api/v1/users/123 # Delete
# ❌ Špatně
GET /api/getUsers
POST /api/deleteUser/123
GET /api/user/123/getOrders
Status kódy
- 200: OK (GET, PUT, PATCH)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Bad Request (validace)
- 401: Unauthorized (nepřihlášen)
- 403: Forbidden (nemá oprávnění)
- 404: Not Found
- 409: Conflict (duplicate)
- 422: Unprocessable Entity
- 429: Too Many Requests
- 500: Internal Server Error
Response format
// Success
{ "data": { "id": 123, "name": "Jan" } }
// Error
{ "error": { "code": "VALIDATION_ERROR", "message": "Email is required",
"details": [{ "field": "email", "message": "Required" }] } }
// List with pagination
{ "data": [...], "meta": { "total": 100, "page": 1, "limit": 20 } }
Klíčový takeaway
Nouns v URL, HTTP metody pro akce, správné status kódy, konzistentní response format.