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í

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 } }

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

Rate Limiting¶

X-RateLimit-Limit: 100
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

Golden rule¶

API by mělo být intuitivní. Pokud potřebujete dokumentaci k pochopení URL, redesignujte.