Pragmatismus schlägt Purismus
Perfekte REST-Konformität ist kein Selbstzweck. Wichtiger ist, dass deine API konsistent, verständlich und nutzbar bleibt. Regeln dürfen gebogen werden – solange der Nutzen für Entwickler im Vordergrund steht.
Merke: APIs sind für reale Anwendungsfälle da, nicht um ein Spezifikations-Dokument zufriedenzustellen.
Ressourcen immer im Plural
Nutze für Endpoints konsequent die Pluralform. Das schafft Vorhersehbarkeit und Skalierbarkeit.
Schlecht
GET /api/get/project
Gut
GET /api/projects
GET /api/projects/{projectId}
Hierarchische Endpoints nutzen
Zeige Beziehungen durch verschachtelte Strukturen – aber nur, wenn es wirklich Sinn ergibt.
Schlecht
GET /api/evaluation/123/project
Gut
GET /api/projects/123/evaluations
Keine primitiven Werte auf oberster Ebene
API-Responses sollten immer Objekte zurückgeben – niemals nur true, Strings oder Arrays.
true
Gut
{
"isActive": true
}
Arrays immer in Objekten kapseln
Ähnlich wie bei primitiven Werten: niemals rohe Arrays zurückgeben.
Schlecht
[
{ ...project1... },
{ ...project2... }
]
Gut
{
"data": [
{ ...project1... },
{ ...project2... }
],
"paging": {
"limit": 25,
"offset": 0,
"total": 142
}
}
Keine Map-Strukturen im JSON
Dynamische Keys erschweren Typisierung und Wartbarkeit.
Schlecht
{
"KEY1": { "id": "KEY1", "foo": "bar" },
"KEY2": { "id": "KEY2", "foo": "bar" }
}
Gut
{
"data": [
{ "id": "KEY1", "foo": "bar" },
{ "id": "KEY2", "foo": "bar" }
]
}
Kebab-Case für Pfade
Alle URL-Segmente in kebab-case halten.
Gut
/projects/{projectId}/management/reset-members
camelCase für Felder & Query-Parameter
JSON-Felder und Query-Parameter in camelCase halten.
Schlecht
GET /api/projects?sort=project_name
POST /api/projects
{
"project_name": "Meta",
"project_age": 12
}
Gut
GET /api/projects?sort=projectName
POST /api/projects
{
"projectName": "Meta",
"projectAge": 12
}
Keine Abkürzungen für Property-Namen
Klarheit geht vor Kürze.
Schlecht
{
"pId": "922414a2-5f52-442d-9729-ad456ae30652"
}
Gut
{
"projectId": "922414a2-5f52-442d-9729-ad456ae30652"
}
In Use Cases denken, nicht in CRUD
APIs sollen Business-Logik widerspiegeln, nicht nur CRUD-Operationen.
Schlecht
PUT /api/projects/123/user/456/assign
Gut
POST /api/projects/123/assign
Datum/Zeit im ISO8601-Format (UTC)
Immer ISO8601 mit UTC-Zeitzone nutzen.
Schlecht
2024-01-12T15:07:17+01:00
Gut
2024-01-12T14:07:17Z
API-Versionierung im Pfad
Bei Breaking Changes neue Version im Pfad.
Alt (deprecated)
GET /api/projects
Neu
GET /api/v2/projects
Keine internen Details preisgeben
Stacktraces oder Systemfehler gehören nicht in die Response.
Schlecht
{
"error": "Internal Server Error",
"details": "Stack trace: [full error details]"
}
Gut
{
"error": "Etwas ist schiefgelaufen. Bitte versuchen Sie es später erneut."
}
Custom Headers ohne „X-“ Prefix
Stattdessen kebab-case verwenden.
Gut
custom-header
Standard-Pagination nutzen
Query-Parameter für Pagination.
Request
GET /projects?page=2&size=15
Response
{
"data": [{...}, {...}],
"page": {
"page": 2,
"size": 15,
"totalPages": 90,
"totalElements": 1333
}
}
Einheitliches Error-Response-Format
Immer konsistent bleiben.
Beispiel
{
"status": "BAD_REQUEST",
"code": 400,
"timestamp": "2025-04-20T11:23:15Z",
"errors": [
{
"type": "VALIDATION_ERROR",
"message": "Provided value does not match pattern",
"field": "key"
},
{
"type": "VALIDATION_ERROR",
"message": "Field is missing",
"field": "test"
}
]
}
Einheitliche Such-Syntax
Für Full-Text-Suche immer den Parameter q nutzen.
GET /projects?q=demo
Fazit
Mit diesen 18 Best Practices baust du REST APIs, die skalierbar, konsistent und zukunftssicher sind. Von Naming Conventions über Pagination und Fehlerbehandlung bis zur Versionierung – diese Regeln helfen, APIs zu entwickeln, die sowohl für interne Teams als auch für externe Entwickler leicht verständlich, erweiterbar und robust sind.
Folge diesen Prinzipien, um typische Stolperfallen zu vermeiden und langfristig erfolgreiche API-Ökosysteme aufzubauen.
Geschrieben mit ❤️ von Fivesec
