REST ist der De-facto-Standard fuer Web-APIs. So designen Sie es richtig.
REST-Prinzipien¶
- Stateless – Server haelt keine Session
- Resource-basiert – URL repraesentiert eine Ressource
- HTTP-Methoden fuer Operationen
- Standardisierte Statuscodes
CRUD-Mapping¶
GET /users -> Liste
GET /users/123 -> Detail
POST /users -> Erstellen
PUT /users/123 -> Vollstaendiges Update
PATCH /users/123 -> Teilweises Update
DELETE /users/123 -> Loeschen
Response-Format¶
// Success
{ “data”: { “id”: 123, “name”: “Hans” } }
// Error
{ “error”: { “code”: “NOT_FOUND”, “message”: “User not found” } }
// List
{ “data”: […], “pagination”: { “total”: 100, “page”: 1, “limit”: 20 } }
Authentifizierung¶
- API Key – einfach, fuer Server-zu-Server
- Bearer Token (JWT) – Standard fuer SPA/Mobile
- OAuth 2.0 – fuer Drittanbieter-Zugriff
- Session Cookie – fuer traditionelle Web-Apps
Versionierung¶
Der vollstaendige Leitfaden zu REST API¶
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
Paginierung¶
Offset¶
GET /users?page=2&limit=20
Cursor (besser fuer grosse Datensaetze)¶
GET /users?cursor=abc123&limit=20
Goldene Regel¶
Eine API sollte intuitiv sein. Wenn Sie Dokumentation brauchen, um die URL zu verstehen, ueberarbeiten Sie das Design.