Manuál
Kompletní průvodce REST API
REST je de-facto standard pro webové API. Tady je jak ho designovat správně.
REST principy
- Stateless — server nedrží session
- Resource-based — URL reprezentuje resource
- HTTP metody pro operace
- Standardní status codes
CRUD mapping
GET /users → seznam
GET /users/123 → detail
POST /users → vytvoření
PUT /users/123 → celý update
PATCH /users/123 → částečný update
DELETE /users/123 → smazání
GET /users/123 → detail
POST /users → vytvoření
PUT /users/123 → celý update
PATCH /users/123 → částečný update
DELETE /users/123 → smazání
Response format
// Success
{ "data": { "id": 123, "name": "Jan" } }
// Error
{ "error": { "code": "NOT_FOUND", "message": "User not found" } }
// List
{ "data": [...], "pagination": { "total": 100, "page": 1, "limit": 20 } }
{ "data": { "id": 123, "name": "Jan" } }
// Error
{ "error": { "code": "NOT_FOUND", "message": "User not found" } }
// List
{ "data": [...], "pagination": { "total": 100, "page": 1, "limit": 20 } }
Autentizace
- API Key — jednoduchý, pro server-to-server
- Bearer Token (JWT) — standard pro SPA/mobile
- OAuth 2.0 — pro third-party přístup
- Session cookie — pro tradiční web apps
Versioning
# URL path (doporučeno)
GET /v1/users
GET /v2/users
# Header
Accept: application/vnd.myapi.v1+json
GET /v1/users
GET /v2/users
# Header
Accept: application/vnd.myapi.v1+json
Rate Limiting
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707900000
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707900000
Pagination
# Offset
GET /users?page=2&limit=20
# Cursor (lepší pro velké datasety)
GET /users?cursor=abc123&limit=20
GET /users?page=2&limit=20
# Cursor (lepší pro velké datasety)
GET /users?cursor=abc123&limit=20
Golden rule
API by mělo být intuitivní. Pokud potřebujete dokumentaci k pochopení URL, redesignujte.