/
Capacieitsverzoek Service API

Capacieitsverzoek Service API

 

 

De Swagger van de Capaciteitsverzoek Service API vind u hier:

acceptatie omgeving: https://services-acc.mijnaansluiting.nl/services/capaciteitsverzoek/swagger/index.html

productie omgeving:

Inleiding

De Capaciteitsverzoek Service is een cruciaal onderdeel van het http://Mijnaansluiting.nl platform, is ontworpen met een sterke nadruk op gebruiksvriendelijkheid. Deze service stelt gebruikers in staat om capaciteitsverzoeken snel en efficiënt op te vragen.

Transformatie naar REST-gebaseerde Service

De overgang naar een REST-gebaseerde service heeft aanzienlijke verbeteringen met zich meegebracht:

  • Meer flexibiliteit en schaalbaarheid

  • Betere compatibiliteit met moderne architecturen, middleware en netwerken

Deze verbeteringen hebben een directe positieve impact op de gebruikerservaring, verkorten de doorlooptijd van aanvragen en verhogen de algehele efficiëntie van netwerkbeheer. Door deze transitie kunnen gebruikers nu profiteren van een robuustere en toekomstbestendige infrastructuur, wat resulteert in een meer gestroomlijnd en betrouwbaar aanvraagproces.

Handleiding

1. GET /v1/capaciteitsverzoeken/{capaciteitsverzoekID}/bijlagen/{bijlageID}

Beschrijving: Dit endpoint wordt gebruikt om een bijlage op te halen die bij een capaciteitsverzoek hoort.

 

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Ja

String

application/json

Request

Bij het opvragen van een bijlage met de GET /v1/capaciteitsverzoeken/{capaciteitsverzoekID}/attachment/{attachmentID} methode, moeten de volgende url-parameters worden gebruikt.

  1. capaciteitsverzoekID (int): De Id van de capaciteitsverzoek.

  2. attachmentID (int): De Id van de op te halen bijlage

codevoorbeeld (curl):

curl -X GET\ -H "Authorization: Bearer [[accessToken]]"\ -H "Accept: application/json"\ -H "Content-Type: application/json"\ "//v1/capaciteitsverzoeken/{capaciteitsverzoekID}/attachment/{attachmentID}"

Additionele informatie

De hier beschreven functionaliteit biedt een endpoint om informatie over een specifieke bijlage van een capaciteitsverzoek op te halen.

Wanneer de bijlage met het opgegeven identificatienummer in de achterliggende database of service bekend is, ontvangt de gebruiker een response met de statuscode 200 (OK). Deze succesvolle response bevat een JSON-object van het type Attachment. Dit bevat wat metadata van de bijlage en de url wat gebruikt kan worden om de bijlage te downloaden. Dit url bevat een SAS-token die 1 minuut geldig is.

Indien de betreffende bijlage niet bestaat of niet gevonden kan worden, retourneert de service een 404 (Not Found). Dit is een belangrijk signaal voor de aanroepende partij: ofwel het opgegeven combinatie van capaciteitsverzoekID en attachmentID is onjuist, ofwel de gevraagde informatie is niet langer beschikbaar in het systeem.

 

2. GET /v1/capaciteitsverzoeken

Korte beschrijving: Dit endpoint wordt gebruikt om een lijst van capaciteitsverzoeken op te halen. Het /v1/capaciteitsverzoeken endpoint met de GET-methode biedt de functionaliteit om een gefilterde lijst van capaciteitsverzoek items op te halen.

 

Bij het opvragen van een lijst van capaciteitsverzoeken met de GET /v1/capaciteitsverzoek methode, kunnen de volgende queryparameters worden gebruikt om de resultaten te filteren en te pagineren:

  1. status (string): Filter de capaciteitsverzoeken op basis van hun status.

  2. submittedFrom (string, date-time): Filter capaciteitsverzoeken die zijn ingediend vanaf een specifieke datum en tijd.

  3. submittedTo (string, date-time): Filter capaciteitsverzoeken die zijn ingediend tot een specifieke datum en tijd.

  4. _offset (integer, int32) (default: 100): Het aantal resultaten om over te slaan (voor paginering).

  5. _limit (integer, int32) (default: 0): Het aantal resultaten om terug te geven (voor paginering).

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Nee

String

application/json

codevoorbeeld (curl)

curl -X GET\ -H "Authorization: Bearer [[accessToken]]"\ -H "Accept: application/json"\ -H "Content-Type: application/json"\ "//v1/capaciteitsverzoeken?status=&submittedFrom=&submittedTo=&_offset=&_limit="

Additionele informatie

De hier beschreven functionaliteit biedt een endpoint om een lijst van capaciteitsverzoeken op te halen op basis van een filter waarbij de submittedFrom en submittedTo query parameters verplicht zijn.

De mogelijke statussen die gebruikt kunnen worden voor capaciteitsverzoeken zijn:

  • Submitted

  • UnderReview

  • Rejected

  • Approved

  • Waitlist

  • PartiallyGranted

  • Granted

Indien er capaciteitsverzoeken gevonden kunnen worden op basis van de filters, ontvangt de gebruiker een response met statuscode 200 (OK). Deze succesvolle response bevat een JSON-object van het type capaciteitsverzoekIDPaginResponse. Hierbij geeft de total het aantal items aan die gevonden zijn op basis van de filters. data is een lijst van het type object capaciteitsverzoekID waarbij de maximale lengte gelijk is aan de opgegeven _limit parameter.

 

3. GET /v1/capaciteitsverzoeken/{id}

Beschrijving: Dit endpoint wordt gebruikt om een capaciteitsverzoek op te halen.

 

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Ja

String

application/json

Request

Bij het opvragen van een capaciteitsverzoek met de GET /v1/capaciteitsverzoeken/{id} methode, moeten de volgende urlparameters worden gebruikt.

  1. id (int): De Id van de capaciteitsverzoek.

codevoorbeeld (curl):

curl -X GET\ -H "Authorization: Bearer [[accessToken]]"\ -H "Accept: application/json"\ -H "Content-Type: application/json"\ "//v1/capaciteitsverzoeken/{id}"

Additionele informatie

De hier beschreven functionaliteit biedt een endpoint om informatie over een specifieke capaciteitsverzoek op te halen.

Wanneer de capaciteitsverzoek met het opgegeven identificatienummer in de achterliggende database of service bekend is, ontvangt de gebruiker een response met de statuscode 200 (OK). Deze succesvolle response bevat een JSON-object van het type capaciteitsverzoek.

Indien de betreffende capaciteitsverzoek niet bestaat of niet gevonden kan worden, retourneert de service een 404 (Not Found). Dit is een belangrijk signaal voor de aanroepende partij: ofwel het opgegeven capaciteitsverzoekID is onjuist, ofwel de gevraagde informatie is niet langer beschikbaar in het systeem.

4. PATCH /v1/capaciteitsverzoeken/{id}

Beschrijving: Dit endpoint wordt gebruikt om de status van een capaciteitsverzoek te wijzigen.

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Ja

String

application/json

Request Body

Parameter

Verplicht

Type

Beschrijving

Parameter

Verplicht

Type

Beschrijving

status

Nee

String

De aangepaste status

additionelInformation

Nee

String

Additionele melding

wachtlijstDate

Nee

Datetime

De datum tot wanneer het op de wachtlijst staat

Request

Bij het aanpassen van de status van een capaciteitsverzoek met de PATCH /capaciteitsverzoek/{id} methode, moeten de volgende url-parameters worden gebruikt:

  1. id (string): De Id van de capaciteitsverzoek.

codevoorbeeld (curl):

curl -X PATCH\ -H "Authorization: Bearer [[accessToken]]"\ -H "Accept: application/json"\ -H "Content-Type: application/json"\ "//v1/capaciteitsverzoeken/{id}"

Additionele informatie

De hier beschreven functionaliteit biedt een endpoint om de status van een capaciteitsverzoek aan te passen.

 

Wanneer de status van de capaciteitsverzoek succesvol is gewijzigd krijgt de gebruiken een response met statuscode 204 (No Content).

Indien de betreffende capaciteitsverzoek niet bestaat of niet gevonden kan worden, retourneert de service een 404 (Not Found). Dit is een belangrijk signaal voor de aanroepende partij: ofwel het opgegeven capaciteitsverzoekID is onjuist, ofwel de gevraagde informatie is niet langer beschikbaar in het systeem.

De mogelijke statussen die gebruikt kunnen worden voor capaciteitsverzoeken zijn:

  • UnderReview

  • Rejected

  • Approved

  • Waitlist

  • PartiallyGranted

  • Granted

Een status wijziging moet voldoen aan bepaalde criterias. Zo niet, dan krijgt de gebruiker een response met statuscode 422 (Unprocessible Entity). De criterias zijn als volgt:

  1. WachtlijstDate mag alleen meegegeven worden bij de volgende statussen:

  • Waitlist

  • PartiallyGranted

 

 

5. GET /v1/capaciteitsverzoeken/{id}/versions

Korte beschrijving: Dit endpoint wordt gebruikt om een lijst van versies van een capaciteitsverzoek op te halen.

 

Bij het opvragen van een lijst van versies van een capaciteitsverzoek met de GET /v1/capaciteitsverzoek/{id}/versions methode, moeten de volgende url-parameters worden gebruikt.

  1. id (int): De Id van de capaciteitsverzoek.

Headers

Header Name

Verplicht

Type

Beschrijving

Header Name

Verplicht

Type

Beschrijving

Authorization

Ja

String

JWT Bearer token voor authenticatie

Content-Type

Nee

String

application/json

codevoorbeeld (curl)

curl -X GET\ -H "Authorization: Bearer [[accessToken]]"\ -H "Accept: application/json"\ -H "Content-Type: application/json"\ "//v1/capaciteitsverzoeken/{id}/versions"

Additionele informatie

Dit is functionaliteit die in de toekomst ontwikkelt zal worden en wordt op dit moment niet gebruikt. Als er iets gewijzigd moet worden aan de capaciteitsverzoek dan kan een aanvrager dit doen en hoeft de aanvrager geen nieuwe capaciteitsverzoek in te dienen. Er wordt een nieuwe versie aangemaakt.

 

 

6. HTTP return status codes

Statuscode

Betekenis

Beschrijving

Statuscode

Betekenis

Beschrijving

200

OK

Het verzoek is geslaagd.

201

Created

Het verzoek is geslaagd en er is een nieuwe resource aangemaakt.

204

No Content

Het verzoek is geslaagd, maar er is geen inhoud om terug te sturen.

400

Bad Request

De server kon het verzoek niet begrijpen vanwege een onjuiste syntax.

401

Unauthorized

Authenticatie is vereist en is mislukt of nog niet verstrekt.

403

Forbidden

De server begrijpt het verzoek, maar weigert het uit te voeren.

404

Not Found

De gevraagde resource kon niet worden gevonden op de server.

422

Unprocessable Entity

De server kon het verzoek niet verwerken vanwege een businessrule

500

Internal Server Error

De server heeft een fout gemaakt en kon het verzoek niet voltooien.

502

Bad Gateway

De server ontving een ongeldige reactie van de upstream-server.

503

Service Unavailable

De server is momenteel niet beschikbaar (door overbelasting of onderhoud).

 

Inhoudsopgave