OSR:API/V2/API V2 naar V3 wijzigingen

Wijzigingen van de OSR API V2 naar V3

Het OSR wordt aangepast zodat schoolbesturen ook op bestuursniveau hun leverancier/systemen kunnen mandateren.
Er wordt per dienst/service ingesteld of mandaten per school of per bestuur moeten worden vastgelegd. Voor deze uitbreiding wordt een nieuwe versie (V3) van de API ontwikkeld.

Met de introductie van deze nieuwe versie van de OSR API zijn er verschillende wijzigingen doorgevoerd ten opzichte van de huidige versie 2.
Onderstaande documentatie geeft een overzicht van de belangrijkste veranderingen, inclusief nieuwe functionaliteiten, verwijderde of aangepaste endpoints
en verbeteringen op het gebied van beveiliging en prestaties.

Deze pagina is bedoeld voor ontwikkelaars en technische beheerders die werken met de OSR API en hun implementaties willen upgraden naar de nieuwste versie.
Door de wijzigingen tijdig te begrijpen en door te voeren, zorg je ervoor dat je applicaties compatibel blijven en profiteren van de nieuwste optimalisaties.

Bekijk hieronder de gedetailleerde wijzigingen en aanbevelingen voor een soepele migratie.

Wijzigingen per API endpoint

Type wijzigingen	URI	Wijzigingen API V3
URIResponses	GET /boards/{bgeCode}	URI-parameter "{id}" wordt "{bgeCode}" Responseveld "number" wordt "bgeCode"
Responses	POST /endpoints	Bij gebruik van het token van een mandaat, welke op bestuursniveau is aangemaakt geeft de API terug: HTTP 400: The given service version does not allow endpoint registrations
Responses	GET /endpoints	Bij gebruik van de versie naamruimte van een dienst, welke alleen mandaten op bestuursniveau toestaat geeft de API een HTTP 200 met lege lijst terug
URI	GET /endpoints/{uuid} PUT /endpoints/{uuid} DELETE /endpoints/{uuid}	URI-parameter "{id}" wordt "{uuid}"
URIResponses	GET /endpoints/available-routing-id	Deze vervangt het API endpoint "GET available_routing_id". Bij gebruik van de versie naamruimte van een dienst, welke alleen mandaten op bestuursniveau toestaat geeft de API een HTTP 200 met lege lijst terug
Nieuw	GET /health	Dit API endpoint geeft aan of de OSR API bereikbaar is en juist functioneert Hoofdstatus "UP" en "DOWN" voorziet in de generieke status Aanvankelijk wordt hier alleen een basale ping uitgevoerd
URIParametersResponses	GET /mandates/services/{serviceCode}/schools/{oieCode}/suppliers/{supplierOin}	Deze vervangt het API endpoint "GET /mandates" Geeft alleen mandaten op schoolniveau terug in de response Parameter "service_version_namespace" wordt verwijderd De parameters "serviceCode", "schoolOin" en "supplierOin" zijn verplicht en verplaatst naar de URI
Nieuw	GET /mandates/services/{serviceCode}/boards/{bgeCode}/suppliers/{supplierOin}	Dit API endpoint geeft alleen mandaten op bestuursniveau terug in de response Parameter "boardBgeCode" wordt gebruikt om het schoolbestuur te identificeren Responseveld _links.board { "href": "string" } bevat een link naar het bij het mandaat behorende schoolbestuur
URIResponses	GET /mandates/{uuid}	URI-parameter "{id}" wordt "{uuid}"; Geeft zowel mandaten op school- als bestuursniveau terug Responseveld _links.board { "href": "string" } bevat een link naar het bij het mandaat behorende schoolbestuur Responseveld "_links.board" is altijd gevuld, zowel bij een mandaat op school- als bestuursniveau Responseveld "_links.school" geeft uiteraard alleen een waarde bij een mandaat op schoolniveau, anders is deze null
ParametersResponses	GET /schools	"oa_id" komt niet meer voor als parameter en in responses Responseveld "brin" wordt "oieCode"
ParametersResponses	GET /schools/{oieCode}	URI-parameter "{id}" wordt "{oieCode}" "oa_id" komt niet meer voor als parameter en in responses Responseveld "brin" wordt "oieCode"
Responses	GET /school-mandates	"school_oa_id" komt niet meer voor in responses
Parameters	GET /services/{uuid}	URI-parameter "{id}" wordt "{uuid}"
Parameters	GET /service-versions/{uuid}	URI-parameter "{id}" wordt "{uuid}"
Responses	POST /service-versions/copy-endpoints-from-service-version	Als de parameters "serviceVersionNamespaceToCopyTo" óf "serviceVersionNamespaceToCopyFrom" betrekking hebben op een dienst welke alleen mandaten op bestuursniveau toestaat geeft de API terug: HTTP 400: The given service version(s) do not allow endpoint registrations

Algemene aandachtspunten

• Alle responsevelden worden in V3 teruggegeven in camelCase in plaats van snake_case in V2
• Het is aanvankelijk niet mogelijk om endpoints aan te maken voor mandaten op bestuursniveau