De Devschuur Coffee Corner - Iteratie ⑬

[Kalentum]

Spooksel schreef op vrijdag 19 september 2025 @ 12:20:
Ok, misschien dat ik gek ben... if so, do tell me.

Maar ik heb dus vanmorgen een discussie gehad met een developer die van mening is dat REST API's altijd alleen maar HTTP code 200 OK terug mogen geven!

Dit omdat volgens hem de statuscodes gaan over communicatie tussen de client en server en dus is 200 de enige reactie die aangeeft dat de communicatie ok was! Dus als de API een verzoek niet kan afhandelen, bijvoorbeeld om dat de validatie van de inhoud mislukt, dan moet je HTTP 200 OK terug geven met bijvoorbeeld als body:

code:

{
    "status":"error",
    "message":"Hier de reden van het mislukken van de request"
}

Terwijl ik dan bijvoorbeeld denk, dan moet je een HTTP 400 Bad Request terug geven met als inhoud:

code:

{
    "message":"Hier de reden van het mislukken van de request"
}

Ben ik nou zo gek om te denken dat je die HTTP status codes wel degelijk moet kunnen gebruiken om iets inhoudelijks te zeggen over de afwikkeling van een request?

Nee hoor je bent niet gek. Genoeg REST API's die 404 Not founds doen, PUT/PATCH correct implementeren, location headers gebruiken etc

Maar je ziet wel veel verschillende implementaties.

[ Voor 3% gewijzigd door Kalentum op 19-09-2025 12:49 ]

[sky-]

Zo lang het gedrag van de API (goed) gedocumenteerd is, is er wat mij betreft niets aan de hand.

[mbe81]

Spooksel schreef op vrijdag 19 september 2025 @ 12:20:
Ok, misschien dat ik gek ben... if so, do tell me.

Maar ik heb dus vanmorgen een discussie gehad met een developer die van mening is dat REST API's altijd alleen maar HTTP code 200 OK terug mogen geven!

Dit omdat volgens hem de statuscodes gaan over communicatie tussen de client en server en dus is 200 de enige reactie die aangeeft dat de communicatie ok was! Dus als de API een verzoek niet kan afhandelen, bijvoorbeeld om dat de validatie van de inhoud mislukt, dan moet je HTTP 200 OK terug geven met bijvoorbeeld als body:

code:

{
    "status":"error",
    "message":"Hier de reden van het mislukken van de request"
}

Terwijl ik dan bijvoorbeeld denk, dan moet je een HTTP 400 Bad Request terug geven met als inhoud:

code:

{
    "message":"Hier de reden van het mislukken van de request"
}

Ben ik nou zo gek om te denken dat je die HTTP status codes wel degelijk moet kunnen gebruiken om iets inhoudelijks te zeggen over de afwikkeling van een request?

Die developer komt vast nog uit het SOAP tijdperk? Daar is dit volgens mijn gemeengoed (Ook omdat SOAP niet altijd over http gaat en http echt gezien werd als transportprotocol). Een REST-api gaat altijd via http en is daardoor meer verweven. Daarom is daar wel de best practice om de statuscodes van de http response onderdeel te laten zijn van het resultaat.
Je definieert zelfs expliciet in een OpenAPI specificatie de response per statuscode.

[daily.data.inj]

Spooksel schreef op vrijdag 19 september 2025 @ 12:20:
Ok, misschien dat ik gek ben... if so, do tell me.

Maar ik heb dus vanmorgen een discussie gehad met een developer die van mening is dat REST API's altijd alleen maar HTTP code 200 OK terug mogen geven!

Dit omdat volgens hem de statuscodes gaan over communicatie tussen de client en server en dus is 200 de enige reactie die aangeeft dat de communicatie ok was! Dus als de API een verzoek niet kan afhandelen, bijvoorbeeld om dat de validatie van de inhoud mislukt, dan moet je HTTP 200 OK terug geven met bijvoorbeeld als body:

code:

{
    "status":"error",
    "message":"Hier de reden van het mislukken van de request"
}

Terwijl ik dan bijvoorbeeld denk, dan moet je een HTTP 400 Bad Request terug geven met als inhoud:

code:

{
    "message":"Hier de reden van het mislukken van de request"
}

Ben ik nou zo gek om te denken dat je die HTTP status codes wel degelijk moet kunnen gebruiken om iets inhoudelijks te zeggen over de afwikkeling van een request?

Altijd leuk dat soort gesprekken, soms oprecht omdat het een mogelijkheid is om de onderwerpen en de achterliggende rationales nog beter kan doorgronden en soms... van ohh here we go again .

Ik merk dat ik de laatste tijd vooral zoveel mogelijk informatie van 'authorative sources' probeer te raadplegen en te gebruiken. Ze zijn immers authorative voor een reden en verwoorden het vaak stukken beter dan dat ik zelf kan.
In dit geval zou ik wat RFC# delen die beschrijven hoe de HTTP status codes zijn bedoeld en waarom, bijv. RFC2616: https://www.rfc-editor.org/rfc/rfc2616#section-6.1.1.

Zie trouwens dat Wikipedia ook een mooi overzicht heeft inclusief de bijgewerkte RFC's Wikipedia: List of HTTP status codes

[thof]

Als we dan toch met RFC's bezig zijn, dan is RFC9457 'Problem Details for HTTP APIs' ook wel handig om door te nemen. Die gaat ook over hoe foutafhandeling te doen, mede omdat een HTTP status code meestal niet genoeg informatie geeft. Dit zit overigens (gedeeltelijk) ook ingebakken in ASP.NET, voor de .NET collega's hier. Anyway iets meer standaardisatie rondom foutberichten kan de afhandeling ervan best helpen.

Voorbeeld responses uit de RFC:

code:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

code:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.net/validation-error",
 "title": "Your request is not valid.",
 "errors": [
             {
               "detail": "must be a positive integer",
               "pointer": "#/age"
             },
             {
               "detail": "must be 'green', 'red' or 'blue'",
               "pointer": "#/profile/color"
             }
          ]
}

[Spooksel]

sky- schreef op vrijdag 19 september 2025 @ 12:48:
Zo lang het gedrag van de API (goed) gedocumenteerd is, is er wat mij betreft niets aan de hand.

Dit ben ik ook met je eens hoor, maar het probleem is hier dat ik degene ben die een API gemaakt heeft en daarin geef ik bijvoorbeeld HTTP 422 Unprocessable Content terug indien een request in principe helemaal valide is, maar toch niet verwerkt kan worden door de server. Ik heb die API zo ontworpen, maar nu roept de andere deverloper dat hij dus mijn reacties niet kan uitlezen omdat ie alleen maar HTTP 200 Ok verwacht , want...

quote: Andere developer

HTTP is een communicatieprotocol. Dus de foutcodes gaan over de communicatie, niet over de inhoud. Dus als een parameter ontbreekt dan verloopt de communicatie niet goed. Of als je geen toegang hebt (403) heb je geen communicatie.

Een casus waarin dit kan gebeuren is bijvoorbeeld als een cursist zich wil inschrijven op een cursus die in de administratie op status 'GAAT NIET DOOR' gezet is en de website hier nog niet van op de hoogte is (ik zou zo graag willen dat die mensen webhooks leren gebruiken), omdat de update job van de websites nog niet gelopen heeft.

De client maakt in dit geval dus een volledig geldig geformuleerd verzoek voor het plaatsen van een inschrijving in de administratie, maar doordat de status van de gewenste cursus het niet toelaat krijg je dus dat het resultaat is dat je geen inschrijving hebt.

In mijn API is het dus zo dat als er een parameter ontbreekt (zie voorbeeld van de andere developer hierboven), dan krijg je een HTTP 400 Bad Request terug en staat er in de body een JSON string met uitleg waarom je deze reactie krijgt, namelijk dat er een parameter ontbreekt. Dit is gewoon goeie communicatie, hij wil er alleen niet aan om het uit te lezen.

Als je je API zo opgebouwd en gedocumenteerd hebt dat je alles via HTTP 200 Ok beantwoord, prima. Maar ik heb dat dus niet, ik geef diverse HTTP statussen terug om aan te geven wanneer iets goed of niet goed gaat en dat heb ik ook zo gedocumenteerd.

[ Voor 9% gewijzigd door Spooksel op 19-09-2025 15:57 ]

[wackmaniac]

omdat ie alleen maar HTTP 200 Ok verwacht

Lijkt me een uitstekend moment om dat dan te verbeteren

[Voutloos]

De server is er al, de werking is bij deze duidelijk.
Als je 3x om je eigen voorkeur bij mij als dienstverlener zeurt, heb ik totaal geen moeite om het antwoord te sturen inc je manager in CC dat enige vertraging van implementatie een client keuze is; de dienst werkt al voor vele anderen.

[Jolijter]

Oef, alleen HTTP 200 erkennen gaat wel heel ver. Zoals de andere developer aangeeft is het de status omtrend de communicatie. Wanneer het om een REST API gaat is een HTTP 404 een prima reactie op een resource die gewoon niet bestaat. Als je een GET op /order/123 doet en die bestaat niet, is HTTP 404 een prima response. Dat je daarmee niet het verschil ziet tussen /0rder/123 die ook een HTTP 404 kan geven omdat je een typo hebt gemaakt maakt het wat verwarrend, in beide gevallen ligt het aan de client die een niet bestaande resource opvraagt. Nog leuker zou zijn als je een HTTP 410 geeft op een resource die wel bestaan heeft om dat verschil ook nog duidelijker te maken.

Ik kan me herinneren dat ik weleens een HTTP 400 heb teruggegeven wanneer een resource waar naar wordt verwezen in een POST request niet bestaat. Als je kijkt naar de RFC voor HTTP 400 klinkt dat niet als de juiste status want dat zou alleen om de syntax van het request moeten gaan, niet om de inhoud ervan. Een request dat een HTTP 400 heeft zou zonder wijzigingen in het request niet tot wat anders dan een HTTP 400 moeten leiden. Welke HTTP status het dan wel zou moeten zijn is me nog niet helemaal duidelijk. Volgens ChatGPT zou het een HTTP 422 kunnen zijn.

[RobertMe]

Het wordt pas leuk als je bewust verkeerde status codes gaat geven. Gewoon altijd esn 404, ook bij toegang geweigerd. Want maak je onderscheid tussen 404 voor bv een order die niet bestaat en 403 voor een order waar de ingelogde gebruiker geen toegang toe heeft "lek" je informatie. Daarom wordt er vaak gekozen voor altijd een 404. Maakt uiteraard bij nummers minder uit dan bij namen. Maar bv GitHub doet dat ook met organisatie en repository namen.

[Marc3l]

Alleen een 200 teruggeven... wat heeft die status dan nog voor zin? 😛 Kan je net zo goed alleen de json message teruggeven.

Maar juist die statussen zijn handig, je weet dan meteen wat er mis is. Nu moet je dat uit de message halen? Bij (automatisch) testen kan je ook testen met het statusnummer, anders moet je bijvoorbeeld een 403 checken aan de hand van message. En mocht dat bericht worden aangepast, dan werkt je test niet meer. Een 403 blijft een 403. Dus zelf geen voorstander om altijd een 200 terug te geven.

[whoami]

Kalentum schreef op vrijdag 19 september 2025 @ 12:46:
[...]


Nee hoor je bent niet gek. Genoeg REST API's die 404 Not founds doen, PUT/PATCH correct implementeren, location headers gebruiken etc

Maar je ziet wel veel verschillende implementaties.

Ook ooit eens tegen een API moeten praten die altijd maar HTTP 200 teruggaf, ook als er iets fout liep. Dat is eigenlijk een hel om tegen te praten. Je moet altijd de response gaan parsen om te weten of je die request kan retryen of niet. Als de juiste statuscodes teruggegeven worden, dan maak je dat alvast al heel wat duidelijker:
- 400 -> het heeft geen zin om te retryen
- 500 -> retry
-> 408 -> retry
-> etc..

[SPee]

Spooksel schreef op vrijdag 19 september 2025 @ 12:20:
Maar ik heb dus vanmorgen een discussie gehad met een developer die van mening is dat REST API's altijd alleen maar HTTP code 200 OK terug mogen geven!

Dit omdat volgens hem de statuscodes gaan over communicatie tussen de client en server en dus is 200 de enige reactie die aangeeft dat de communicatie ok was! Dus als de API een verzoek niet kan afhandelen, bijvoorbeeld om dat de validatie van de inhoud mislukt, dan moet je HTTP 200 OK terug geven

Dat je een reactie terugkrijgt, geeft al aan dat de communicatie ok is!

Een HTTP code geeft een status van een client request aan. En die kan succesvol zijn (200), een fout opleveren (400) of een echte serverfout geven (500).
Want wat denkt hij over een HTTP 404 in de browser? De communicatie met de server was toch immers ok? Daar krijg je toch ook niet een HTTP 200 met tekst "helaas pindakaas" terug als je een niet-bestaand plaatje opvraagt?
Dus nee, dat nummertje gaat niet over de communicatie.

[SPee]

Mugwump schreef op dinsdag 16 september 2025 @ 13:19:
[...]
Hoorde ik daar iemand Confluence roepen?

Ho, wacht! Nog even geduld! Ik ben nog niet klaar met mijn rust rewrite.
Hopelijk ben ik op tijd klaar als ze stoppen met hun datacenter versie. Dus nog even geduld (3 jaar ofzo).
En dan is er eindelijk weer een betere versie van Confluence/Wordpress/CMS/Wiki/Forum om te proberen.

Ik zit nog te denken aan hoe ik het het beste kan demo-en. Ik zat te denken aan een Tweakers lookalike. Maar misschien is The Next Web een betere optie. Even kijken of die domeinnaam beschikbaar is.

[MueR]

Spooksel schreef op vrijdag 19 september 2025 @ 12:20:
Ok, misschien dat ik gek ben... if so, do tell me.

Maar ik heb dus vanmorgen een discussie gehad met een developer die van mening is dat REST API's altijd alleen maar HTTP code 200 OK terug mogen geven!

Ik zou permanent een HTTP 418 teruggeven op zijn API key. Sorry, maar als je vindt dat een API alleen maar een 200 mag teruggeven snap je http niet. Een 404 op een website geeft toch ook een succesvolle communicatie terug? "Ik zoek X. Sorry, ik heb X niet, maar hier heb je een mooie pagina die je dat vertelt".

[DevWouter]

Eigenlijk hoef je er maar twee te weten
400 = Er gaat iets fout aan jouw kant.
500 = Er gaat iets fout aan mijn kant

Alle andere subcodes vereisen dat je weet hoe de applicatie daar op zal moeten reageren, zoals caching, metadata, content negation, of het wel/niet opnieuw moet proberen.

Verder is er geen verbod om je eigen statuscode te gebruiken zolang het maar in de range van 100 t/m 599 zit. Sterker nog de RFC geeft aan dat je ook de range van 600 t/m 999 mag gebruiken voor interne doeleinden.