API HTTP status code voor verlopen contract

[PdeBie]

De situatie:
API voor ophalen van contracten.
Contracten hebben start- en einddatum.
Client vraagt contract op (GET request) van een contract waarvan einddatum verlopen is.

De wensen:
API gooit een exceptie - ContractExpiredException
Verlopen contract gaat niet over de lijn.

De vraag:
Wat zouden jullie als HTTP response verwachten in deze situatie?


Een 500 is het niet, want er is niets mis met de server
Een 403 is het ook niet, want het is niet dat je iets "verboden" doet.

Wat zouden jullie kiezen in deze situatie?

--edit--
Keuze is gemaakt: PdeBie in "API HTTP status code voor verlopen contract"

[ Voor 13% gewijzigd door PdeBie op 27-05-2021 13:47 ]

[DutchKel]

Is het een server error? nee dus geen 5xx
Is het een cliënt error? nee dus geen 4xx

Ik denk dat 204 het beste in de buurt komt. Mogelijk is 200 zelfs nog beter.

[kamerplant]

HTTP 200 en in de inhoud van het bericht aangeven dat het contract verlopen is.

[Knutselsmurf]

Hangt van de exact request af. Als de request is om de gegevens van een specifiek contract op te halen (aan de hand van een id) dan moet je in mijn optiek gewoon de gegevens het het betreffende contract teruggeven, met als contractstatus 'expired'.

Dit is een hele specifieke functionele situatie, die je in mijn optiek niet met een generieke http-status af moet handelen

[Marco1994]

Zou je niet gewoon het contract terug geven (mits de bepaalde user die rechten heeft) en een property meegeven dat deze expired is. In dat geval mag het gewoon een 200 zijn.

Als de business case is dat dit contract niet meer 'gevonden' kan worden. Zou je een 404 kunnen returnen. Maar of het daar beter mee wordt?

[ Voor 29% gewijzigd door Marco1994 op 27-05-2021 13:33 ]

[PdeBie]

kamerplant schreef op donderdag 27 mei 2021 @ 13:30:
HTTP 200 en in de inhoud van het bericht aangeven dat het contract verlopen is.

Nu je het zo stelt klinkt dat inderdaad niet eens zo gek. Ik zat vooral in de 'error mode' te denken.
Maar in principe is het contract gewoon gevonden. Het feit dat hij verlopen is, is business logica.

@Knutselsmurf we willen het contract niet over de lijn sturen als men er verder toch niets mee kan/mag doen.

[ Voor 12% gewijzigd door PdeBie op 27-05-2021 13:33 ]

[Biersteker]

402 Payment Required?

[Haan]

Afhankelijk van hoe e.e.a. precies in elkaar steekt, zou je ook geen exception moeten gooien omdat het in de normale flow valt.
Tenzij het op een ander punt al afgevangen had moeten worden dat je de request in de eerste plaats al niet had mogen maken.

[Mavamaarten]

401 (unauthorized) lijkt mij de meest logische, die wordt eigenlijk altijd gebruikt wanneer een gebruiker geen toegang meer heeft tot een resource. Maar ook 402 (payment required) lijkt me niet verkeerd.

[Knutselsmurf]

PdeBie schreef op donderdag 27 mei 2021 @ 13:32:
[...]


Nu je het zo stelt klinkt dat inderdaad niet eens zo gek. Ik zat vooral in de 'error mode' te denken.
Maar in principe is het contract gewoon gevonden. Het feit dat hij verlopen is, is business logica.

@Knutselsmurf we willen het contract niet over de lijn sturen als men er verder toch niets mee kan/mag doen.

Je kunt er dan uiteraard voor kiezen om inhoudelijk de contractstatus 'Expired' terug te geven, en verder geen andere inhoudelijke gegevens.

Ik bekijk het even vanuit de kant van de api-consumer: Ik vraag af en toe de gegevens van een contract op (om de gegevens in mijn eigen systeem bij te werken) en op een gegeven moment krijg ik bij een specifiek contract-id een http-error. Waarom? Ik verwacht dan eigenlijk als antwoord "Dat contract heb ik voor je, maar die is verlopen", en dus een HTTP-status 200. De aanvraag is volledig legitiem en moet dus ook als zodanig behandeld worden.

Bij pogingen om bewerkingen uit te voeren op een verlopen contract zou ik dan zelf wel een http-status 4xx teruggeven.

[Knutselsmurf]

Biersteker schreef op donderdag 27 mei 2021 @ 13:33:
402 Payment Required?

Hoezo? De api zit toch niet achter een betaalmuur? Dat is gewoon misbruik maken van http-statuscodes, in plaats van een inhoudelijk antwoord (response met status 200) te geven op een legitieme vraag (http-request).

[PdeBie]

Zojuist dit topic aan een collega nog voorgelegd met wie ik over dit dilemma aan het sparren was.

We gaan voor de 200-response met een property 'ContractExpired'. Het contract is tenslotte gewoon gevonden, maar is niet meer geldig.

Thanks voor het mee denken allen!

[Donderpoes]

Kan een contract weer geactiveerd worden? Ja, je zou het in een 409 kunnen plaatsen. Als het contract nooit meer actief kan worden zou je een 410 kunnen overwegen. Al weet ik niet of een 409 alleen voor updates valide is.

[ Voor 15% gewijzigd door Donderpoes op 27-05-2021 13:58 ]

[Arto]

Een andere mogelijkheid is een `401 Unauthorized`, in principe ben je niet meer geautoriseerd om deze resource te bekijken en kun je in de content nog de reden meegeven

[Illusion]

Waaron zou je niet een verlopen contract op mogen/willen vragen?

Wat als ik ruzie heb over een contract dat ondertussen is afgelopen, maar terug wil vinden wat er in stond?

Wat als iemand over een nieuw contract zegt “he dat is raar, stond dat ook al in het oude contract?”

Wat als ik wil weten wat de exacte einddatum van dat verlopen contract is?

[PdeBie]

@Illusion
Even wat benodigde nuancering. De client applicatie die gebruik maakt van deze API bouwen wij zelf ook. De businesslogica die jij hier beschrijft is geen vereiste.

De “contract is verlopen” logica zat eerst in de client applicatie, maar is verplaatst naar de API omdat het daar meer thuis hoort.

[ Voor 32% gewijzigd door PdeBie op 27-05-2021 19:11 ]

[bwerg]

Ik stel me bij "client error" of "server error" de vraag of het door een programmeerfout veroorzaakt wordt die gefixt moet worden (niet-afgevangen exception aan de server-kant, of verkeerde invoer vanuit de client). Zo nee, dan moet het een 2xx-zijn. Kan je client alleen bepaalde informatie achterhalen door te kijken of iets een 4xx- of 5xx-response geeft? Dan is je API gek.

Maar tot die conclusie was je ook al gekomen.

[mrhoeve]

Is HTTP status 410 Gone geen optie? Zie https://httpstatuses.com/410
Denk dat hij gezien de use case het dichtst in de buurt komt?

Niet goed de draad gelezen, @Donderpoes had deze status ook al genoemd. Excuus...

Donderpoes schreef op donderdag 27 mei 2021 @ 13:56:
Kan een contract weer geactiveerd worden? Ja, je zou het in een 409 kunnen plaatsen. Als het contract nooit meer actief kan worden zou je een 410 kunnen overwegen. Al weet ik niet of een 409 alleen voor updates valide is.

[ Voor 61% gewijzigd door mrhoeve op 27-05-2021 23:11 . Reden: Naam van status toegevoegd ter verduidelijking / toevoeging van de opmerking van Donderpoes ]

[DukeBox]

Beetje laat puur voor de vraag, waarom geen 404 ? Er wordt immers geen valide contract gevonden.

[ Voor 21% gewijzigd door DukeBox op 27-05-2021 23:05 ]

[DonJunior]

@DukeBox Liefst wil je natuurlijk helemaal niet 'exception based' programmeren. Dat is een redelijke bad practice. Je hebt het contract gevonden alleen is de datum verlopen dus een 404 is niet correct. Je hebt immers gevonden waar je naar zocht. Wat @kamerplant zegt lijkt me de enige juiste oplossing (200 OK, "Contract verlopen")
kamerplant in "API HTTP status code voor verlopen contract"

[ Voor 10% gewijzigd door DonJunior op 27-05-2021 23:09 ]

[DukeBox]

DonJunior schreef op donderdag 27 mei 2021 @ 23:08:
@DukeBox Liefst wil je natuurlijk helemaal niet 'exception based' programmeren. Dat is een redelijke bad practice. Je hebt het contract gevonden alleen is de datum verlopen dus een 404 is niet correct.

Ik begrijp het maar wat als de vraagstelling was geweest of de get een valide contract oplevert ? Waarom zou een 404 dan onjuist zijn ?

[DonJunior]

@DukeBox Dan is het request nog steeds OK. Immers de server vindt het contract en kan de logica uitvoeren. Het resultaat van de logica is dan echter een 'False'

200 OK
{ isValid: false }

[DukeBox]

@DonJunior Ik ben nog niet overtuigd
Ik vind het helemaal niet raar om de 404 status code te gebruiken voor als iets niet gevonden wordt, met de paar applicaties waar ik mee werk is dat niet niet ongebruikelijk (exact globe/synergy, magento, cerm).
Als ik gegevens opvraag krijg ik een 404 als die er niet zijn of een 200 met de betreffende gegevens.

Maar laat mij maar gewoon eigenwijs zijn hoor, ik ben immers ook niet echt een programmeur

[ Voor 13% gewijzigd door DukeBox op 27-05-2021 23:28 ]

[Gropah]

DukeBox schreef op donderdag 27 mei 2021 @ 23:26:
@DonJunior Ik ben nog niet overtuigd
Ik vind het helemaal niet raar om de 404 status code te gebruiken voor als iets niet gevonden wordt, met de paar applicaties waar ik mee werk is dat niet niet ongebruikelijk (exact globe/synergy, magento, cerm).
Als ik gegevens opvraag krijg ik een 404 als die er niet zijn of een 200 met de betreffende gegevens.

Maar laat mij maar gewoon eigenwijs zijn hoor, ik ben immers ook niet echt een programmeur

Er word wel een contract gevonden. Dat het contract verlopen is, maakt hem niet minder valide. Of een contract wat verlopen is, niet meer valide is hangt af van de situatie. De vraag is of je dat wilt/moet opnemen in de API die het aanlevert. Daarom vind ik zelf een 404 niet logisch.

mrhoeve schreef op donderdag 27 mei 2021 @ 23:01:
Is HTTP status 410 Gone geen optie? Zie https://httpstatuses.com/410
Denk dat hij gezien de use case het dichtst in de buurt komt?

Niet goed de draad gelezen, @Donderpoes had deze status ook al genoemd. Excuus...

[...]

410 vind ik zelf ook niet per se logisch. Die associeer (en interpreteer) ik meer als het pad (/contracts bijvoorbeeld) verwijderd (en dus niet verplaatst) is en ook niet meer beschikbaar komt.

[DukeBox]

Gropah schreef op donderdag 27 mei 2021 @ 23:33:
Er word wel een contract gevonden. Dat het contract verlopen is, maakt hem niet minder valide.

Dat hangt van de vraagstelling/definitie af van valide. Ik vat verlopen op als niet meer valide.
Net als dat een verlopen paspoort niet meer valide is.

Ik begrijp je punt dat je nog steeds een contract vind en dat dan een 404 niet logisch is, vandaar ook de verduidelijking van mijn vraag:

wat als de vraagstelling was geweest of de get een valide contract oplevert ?

404, Not Found is een prima antwoord op de vraag 'heb je een contract X dat niet verlopen is'.

[ Voor 67% gewijzigd door DukeBox op 27-05-2021 23:42 ]

[Gropah]

DukeBox schreef op donderdag 27 mei 2021 @ 23:35:
Dat hangt van de vraagstelling/definitie af van valide. Ik vat verlopen op als niet meer valide.
Net als dat een verlopen paspoort niet meer valide is.

Snap ik, maar:
* een contract wat afgelopen is, nog steeds een valide contract alleen niet meer actief. Stel dat ik telefooncontract heb afgesloten voor een jaar, in 2014. Het contract is (afaik) nog steeds valide, maar afgehandeld.
* een paspoort is volgens mij geen contract dus niet vergelijkbaar.

[...]

404, Not Found is een prima antwoord op de vraag 'heb je een contract X dat niet verlopen is'.

Wellicht, maar de vraagstelling is volgens mij niet 'heb je een contract X dat niet verlopen is', maar "heb je dit contract".

Maar goed, ik denk dat de conclusie is dat er meer context/domeinkennis nodig is om het goed te beantwoorden.

[ Voor 6% gewijzigd door Gropah op 27-05-2021 23:49 ]

[Haan]

offtopic:
Microsoft geeft in Office 365 een 404 bij een link naar een document waar je geen toegang tot hebt. Ik vind dat super onlogisch, waarom geen 403 dan?

[Kalentum]

Haan schreef op vrijdag 28 mei 2021 @ 07:28:

offtopic:
Microsoft geeft in Office 365 een 404 bij een link naar een document waar je geen toegang tot hebt. Ik vind dat super onlogisch, waarom geen 403 dan?

403 betekent dat de resource bestaat. 404 dat de resource niet gevonden kan worden. Mensen met minder goede bedoelingen niet wijzer maken misschien?

[remco_k]

My 2 cents, ook al heeft TS al keuze gemaakt:

De enige goede wat mij betreft: 200 OK
Met het contract in de body, waarin aan een property is te zien dat ie verlopen is.

404 Not found is volledig incorrect. Het contract bestaat immers wel gewoon.
Stel jezelf deze vraag: stel, je wilt verlopen contracten die een bepaalde status hebben wissen. Hoe ga je dat doen als je ze niet eens op kan vragen? Een 404 impliceert dat hij er helemaal niet is, en dat een DELETE method op hetzelfde contract dus ook een 404 zou geven.

403 Forbidden hoor je in dit geval alleen maar te krijgen als je token simpelweg geen toegang heeft tot de resource.
Ik verwacht dat tenminste als ik een 403 krijg.
In dat geval zou b.v. een DELETE request ook een 403 forbidden moeten geven.
Terwijl als je een 403 geeft omdat het contract is verlopen, je die (naar ik aanneem) met een DELETE nog wel kunt wissen. Dat zou ik dan helemaal een vreemde situatie vinden.

Ergo: 200 OK
/body. 😀