Anatomie van een goed ontworpen request
1 / 8
HTTP-methode
GET leest zonder neveneffecten, dus het antwoord kan gecachet worden en de oproep veilig herhaald.
HTTP/1.1 200 OK{ "data": [ { "id": 7731, "total": 1250.0, "status": "open" }, { "id": 7702, "total": 980.5, "status": "open" } ], "hasMore": true, "nextCursor": "def456"}
Illustratief voorbeeld
Ontwerp van RESTful resources
Best practices voor URI-ontwerp
- Gebruik zelfstandige naamwoorden, geen werkwoorden:
/customersniet/getCustomers - Hiërarchische relaties:
/customers/123/orders - Resourcenamen in het meervoud:
/productsniet/product - Gebruik koppeltekens voor leesbaarheid:
/customer-ordersniet/customer_orders - URI's in kleine letters:
/customersniet/Customers
HTTP-methoden en semantiek
| Methode | Doel | Idempotent | Voorbeeld |
|---|---|---|---|
| GET | Resource(s) ophalen | Ja | GET /customers/123 |
| POST | Nieuwe resource aanmaken | Nee | POST /customers |
| PUT | Volledige resource vervangen | Ja | PUT /customers/123 |
| PATCH | Gedeeltelijke update | Nee | PATCH /customers/123 |
| DELETE | Resource verwijderen | Ja | DELETE /customers/123 |
Ontwerp van responses
HTTP-statuscodes
- 200 OK:Geslaagde GET, PUT, PATCH of DELETE
- 201 Created:Geslaagde POST met een Location-header naar de nieuwe resource
- 204 No Content:Geslaagde request zonder responsbody
- 400 Bad Request:Ongeldige requestsyntaxis of validatiefouten
- 401 Unauthorized:Authenticatie vereist
- 403 Forbidden:Geauthenticeerd maar niet geautoriseerd
- 404 Not Found:Resource bestaat niet
- 409 Conflict:Conflict in de status van de resource (bijv. een duplicaat)
- 429 Too Many Requests:Rate limit overschreden
- 500 Internal Server Error:Onafgehandelde serverfout
Formaat van foutresponses
Consistente foutresponses verbeteren de ontwikkelaarservaring:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"target": "email",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
]
}
}Paginering, filtering en sortering
Pagineringsstrategieën
- Op basis van offset:
?skip=20&limit=10- Eenvoudig maar inefficiënt voor grote datasets - Op basis van een cursor:
?cursor=abc123&limit=10- Efficiënt voor realtime data - Op basis van pagina's:
?page=3&pageSize=10- Gebruiksvriendelijk voor paginering in de UI
Neem pagineringsmetadata op in de response: totalCount, hasMore, nextCursor
Filtering en sortering
- Eenvoudige filters:
?status=active&category=electronics - Vergelijkingsoperatoren:
?price[gte]=100&price[lte]=500 - Zoeken in volledige tekst:
?q=laptop&searchFields=name,description - Sorteren:
?sortBy=createdAt&order=desc - Veldselectie:
?fields=id,name,email