OSR:API/V2/API V2 naar V3 wijzigingen

Wijzigingen van de OSR API V2 naar V3

Achtergrond

Het OSR wordt aangepast zodat schoolbesturen ook op bestuursniveau hun systemen kunnen mandateren.

Er kan per dienst worden ingesteld of mandaten per school of per bestuur worden vastgelegd. Voor deze uitbreiding wordt een nieuwe versie (3) van de OSR API ontwikkeld.

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.

Inhoud en impact

Met de introductie van deze nieuwe versie worden 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 hoofdlijnen is de impact beperkt en gaat het met name om het hernoemen van velden en locaties om de API duidelijker en overzichtelijker te maken.
Bovendien sluit deze hiermee beter aan bij vastgestelde standaarden op het gebied van API ontwikkeling.

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 terug: HTTP 200: (lege lijst)
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" (overgang naar hyphen-seperated URIs) 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
Nieuw	GET /mandates/services/{serviceCode}/boards	Dit API endpoint geeft een lijst van besturen terug, waarvan de API-gebruiker (leverancier) op bestuursniveau mandaten heeft ontvangen
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/services/{serviceCode}/schools	Deze vervangt het API endpoint "GET /school-mandates" en geeft een lijst van scholen terug, waarvan de API-gebruiker (leverancier) op schoolniveau mandaten heeft ontvangen "school_oa_id" komt niet meer voor in responses Responseveld "school_brin" wordt "schoolOieCode"
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 ("serviceCode" volstaat voor het vaststellen van de dienst). De parameters voor de dienst, school en leveranciers zijn gestandaardiseerd en verplaatst naar de URI
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"
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.
  Dit omdat de eerste diensten die hier gebruik van maken dit nog niet nodig gaan hebben;
• De API-documentatie (Swagger) zal op een nieuwe URL beschikbaar worden gesteld, waarbij het mogelijk is te schakelen tussen API versies.