Verschillende URL-waardes voor veld 'type' in foutresponse

[melsk-r]

Originally created by tdonker (https://github.com/VNG-Realisatie/BAG-Gemeentelijke-wensen-tav-BAG-Bevragingen/issues/437):

De BRP en BRK APIs hebben als URL-waarde voor veld 'type' in de foutresponse een link naar Microsoft, bijv.:

{ "type": "https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?#System_Net_HttpStatusCode_InternalServerError", "title": "Interne server fout.", "status": 500, "detail": "Onverwachte fout bij raadplegen op burgerservicenummer: Policy Falsified", "instance": "https://www.haalcentraal.nl/haalcentraal/api/brp/ingeschrevenpersonen/999990639", "code": "serverError" }

de BAG API heeft echter een link naar RFC7231 voor hetzelfde veld, bijv.:

{ "type" : "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title" : "Ten minste één parameter moet worden opgegeven.", "status" : 400, "detail" : "Precies 1 parameter van adresseerbaarObjectIdentificatie of locatie moet worden opgegeven", "instance" : "https://api.bag.acceptatie.kadaster.nl/esd/huidigebevragingen/v1/panden?adresseerbaarObjectIdentificatie=0599010000165822&locatie=98095.02%2C438495.09", "code" : "paramsRequired" }

Is dit verschil doelbewust gekozen en valt er wat voor te zeggen om in het van standaardisering dezelfde link eenduidig te hanteren?

[melsk-r]

This comment originally might have been created by someone else.

Deze vraag is beter op zijn plek binnen een van de GitHub repo's van van de genoemde Haal Centraal projecten dan binnen de API Kennisbank repo. Om die reden heb ik dit issue verplaatst naar deze repo.

[melsk-r]

This comment originally might have been created by someone else.

Hallo @tdonker, heb je er als gebruiker (developer die de API gebruikt) "last" van dat deze links verschillend zijn? Of andersom, zou het je tijd besparen, of zou het fouten voorkomen, of op een andere manier voordeel opleveren, wanneer dit gestandaardiseerd zou worden?

[melsk-r]

This comment originally might have been created by someone else.

Het 'type' veld kan worden gebruikt om te voorzien in een url naar een pagina waarop de statuscode wordt verduidelijkt. Het is in principe aan de provider om dit veld te vullen. Binnen de yaml specificaties van de genoemde Haal Centraal API's zijn bij de diverse responses een aantal voorbeelden opgenomen. De providers die deze specificaties hebben geïmplementeerd hoeven deze niet te gebruiken en dat hebben ze ook niet gedaan. Ook binnen de NL API strategie wordt hier volgens ons niets over gezegd. De vraag is of je dit moet willen standaardiseren. Als een provider zelf ergens anders een betere omschrijving heeft, moet hij ook daarnaar kunnen verwijzen.

[melsk-r]

This comment originally might have been created by someone else.

Bedankt voor de reacties. Mijn vraag is wat theoretisch. De ene omschrijving is vaak de andere niet en voor een gebruiker (developer) kan het wellicht verwarrend overkomen als de omschrijving voor dezelfde foutcode verschilt per API en/of anders geïnterpreteerd kan worden. Persoonlijk zou ik er de voorkeur aangeven om zoveel mogelijk naar de IETF standaards (https://datatracker.ietf.org/doc/html/rfc7231) te verwijzen, deze zijn immers internationaal geadopteerd en aanvaard.

[melsk-r]

This comment originally might have been created by someone else.

@melsk-r Als de vraag is of dit gestandaardiseerd moet worden, dan denk ik dat dit issue niet thuis hoort in de BAG repo. Wat wil je dat wij er mee doen? Als HC wil dat dit voor alle HC API's gelijk wordt getrokken, dan zou ik verwachten dat dit issue in HC common repo hoort, omdat daar de specificaties van de responses staan. Een feature beschrijving waarin beschreven staat welke URL wanneer waar ingevuld wordt, zou dan voor iedere API provider uitkomst bieden.

[melsk-r]

This comment originally might have been created by someone else.

wat is de toegevoegde waarde van dit standaardiseren? Het doel van type is een link te geven naar een plek waar de client developer meer toelichting kan vinden over de fout (en hoe die op te lossen). Beste zou zijn als er bij de API een webpagina met -voor de API specifieke- toelichtingen per soort fout zouden worden gemaakt. Dat is voor nu wellicht een brug te ver.

[melsk-r]

This comment originally might have been created by someone else.

@strijm @fsamwel Lijkt mij dat we dit issue kunnen sluiten. Eens? Standaardisatie is n.m.m. niet aan de orde.