Bijlage Service API

De BijlageService een cruciaal onderdeel van het http://Mijnaansluiting.nl platform, is ontworpen met een sterke nadruk op gebruiksvriendelijkheid. Deze service stelt gebruikers in staat om hun bijlagen snel en efficiënt te up- en downloaden en te beheren.

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.

De Bijlage Service API maakt gebruik van SAS-links (Shared Access Signatures) om toegang te verlenen tot bestanden in achterliggende Blob Storage. Deze opzet zorgt ervoor dat er een duidelijk onderscheid is tussen de bijlagen zelf (als metadata-entiteiten) en de werkelijke bestanden die in Blob Storage worden opgeslagen. Hier is hoe dit werkt:

1. Bijlage als Metadata-Entiteit:

   • Elke bijlage in de API wordt vertegenwoordigd door een set van metadata. Deze metadata kan informatie bevatten zoals de bestandsnaam, het type bestand, de grootte, en de verwijzing (URL) naar het bestand in Blob Storage.

   • De bijlage zelf bevat niet het werkelijke bestand, maar fungeert als een soort 'catalogusrecord' dat aangeeft waar het bestand te vinden is en hoe het kan worden benaderd.

2. Werkelijke Bestanden in Blob Storage:

   • De werkelijke bestanden worden veilig opgeslagen in Blob Storage.

   • In plaats van het bestand rechtstreeks via de API te versturen of te ontvangen, genereert de API een SAS-link (Shared Access Signature) die beperkte toegang tot het bestand biedt.

   • Deze SAS-links worden aan de client verstrekt en geven tijdelijke, beveiligde toegang tot het specifieke bestand in Blob Storage. Dit zorgt ervoor dat alleen geautoriseerde gebruikers toegang hebben tot de bestanden.

3. Gebruik van SAS-links:

   • SAS-links bieden gecontroleerde toegang tot bestanden.

   • Dit mechanisme zorgt voor een hoge mate van veiligheid omdat de toegang tot bestanden via deze links nauwkeurig kan worden gecontroleerd en beperkt.

   • De API beheert de levenscyclus van deze SAS-links en zorgt ervoor dat alleen geldige en veilige links worden verstrekt aan geautoriseerde gebruikers of systemen.

4. Voordelen van deze Aanpak:

   • Veiligheid: Door gebruik te maken van SAS-links kan de toegang tot bestanden in Blob Storage streng worden gecontroleerd, wat risico's op onbevoegde toegang minimaliseert.

   • Schaalbaarheid: De opslag van grote bestanden in Blob Storage voorkomt dat de API zelf zwaar wordt belast met data-opslag, waardoor het systeem beter schaalbaar is.

   • Flexibiliteit: De mogelijkheid om toegang tot bestanden dynamisch te regelen via SAS-links maakt het systeem flexibel en makkelijk aanpasbaar aan verschillende beveiligings- en toegangsbehoeften.

In essentie maakt de Bijlage API gebruik van SAS-links om de werkelijke bestanden op een veilige en efficiënte manier te beheren en toegankelijk te maken, terwijl de bijlagen als metadata-entiteiten worden behandeld om de API zelf licht en snel te houden.

Met deze methode kunnen gebruikers een lijst van bijlagen in een aanvraag opvragen. Op de resultaten kan paginering worden toegepast.

Het /aanvraag/{aanvraagId}/bijlage endpoint met de GET-methode biedt de functionaliteit om een lijst van bijage items op te halen.

Bij het opvragen van een lijst van aanvragen met de GET /aanvraag/{aanvraagId}/bijlage methode, kunnen de volgende url-parameters worden gebruikt om de resultaten te filteren en te pagineren:

1. aanvraagId (string): De Id van de aanvraag.

Bij het opvragen van een lijst van aanvragen met de GET /aanvraag/{aanvraagId}/bijlage methode, kunnen de volgende query-parameters worden gebruikt om de resultaten te filteren en te pagineren:

1. skip (integer, int32): Het aantal resultaten om over te slaan (voor paginering).

2. take (integer, int32): Het aantal resultaten om terug te geven (voor paginering).

curl -X GET\
-H "Authorization: Bearer [[accessToken]]"\
-H "Accept: application/json"\
"//aanvraag/{aanvraagId}/bijlage?skip=&take="

Deze methode stelt gebruikers in staat om een bijlage bij een aanvraag op te halen Het aanvraag-ID moet in de URL worden gespecificeerd, evenals de bijlageId.

Het / aanvraag/{aanvraagId}/bijlage/{bijlageId} endpoint met {aanvraagId} en {bijlageId} met de GET-methode biedt de functionaliteit om een bijlage op te halen.

Bij het opvragen van een lijst van aanvragen met de GET /aanvraag/{aanvraagid} methode, kunnen de volgende urlparameters worden gebruikt om de resultaten te filteren en te pagineren:

1. aanvraagId (string): De Id van de op te halen aanvraag.

codevoorbeeld (curl):

curl -X GET\ 
-H "Authorization: Bearer [[accessToken]]"\ 
-H "Accept: application/json"\ 
-H "Content-Type: application/json"\ "//aanvraag/{aanvraagId}/bijlage/{bijlageId}"

Deze methode stelt gebruikers in staat om de statussen van een aansluiting in een specifieke aanvraag bij te werken. Het aanvraag-ID moet in de URL worden gespecificeerd, en de wijzigingen worden doorgegeven in de body van het verzoek.

Het /aanvraag endpoint met {aanvraagId} met de PATCH-methode biedt de functionaliteit om de status van een aansluiting in een een aanvraag te wijzigen.

Bij het aanpassen van een aanvraag met de PATCH /aanvraag/{aanvraagid} methode, kunnen de volgende url-parameters worden gebruikt om de resultaten te filteren en te pagineren:

1. aanvraagId (string): De Id van de aanvraag.

codevoorbeeld (curl):

curl -X GET\ 
-H "Authorization: Bearer [[accessToken]]"\ 
-H "Accept: application/json"\ 
-H "Content-Type: application/json"\ "//aanvraag/{aanvraagId}/verkoopdocument/{verkoopDocumentId}"

Deze methode stelt gebruikers in staat om de statussen vaan aansluitingen een specifieke aanvraag bij te werken. Het aanvraag-ID moet in de URL worden gespecificeerd, en de wijzigingen worden doorgegeven in de body van het verzoek.

Het /aanvraag endpoint met {aanvraagId} met de PATCH-methode biedt de functionaliteit om de status van aansluitingen in een een aanvraag te wijzigen.

Bij het aanpassen van een aanvraag met de PATCH /aanvraag/{aanvraagid} methode, kunnen de volgende url-parameters worden gebruikt om de resultaten te filteren en te pagineren:

1. aanvraagId (string): De Id van de aanvraag.

Uitleg over het bijwerken van aanvragen met PATCH /aanvraag/{aanvraagId}

Bij het bijwerken van een aanvraag met de PATCH /aanvraag/{aanvraagId} methode, kunnen verschillende niveaus van specificatie worden gebruikt om te bepalen welke onderdelen van de aanvraag worden bijgewerkt. Hieronder volgt een gedetailleerde uitleg van de mogelijke scenario's:

1. Specificeer disciplineId's in de body:

   • Als een of meerdere disciplineId's in de body van het verzoek worden gespecificeerd, worden alleen de betreffende disciplineId's bijgewerkt.

2. Specificeer objectId's maar geen disciplineId's in de body:

   • Als een of meerdere objectId's worden gespecificeerd, maar niet de onderliggende disciplineId's, worden alle onderliggende disciplineId's van die objectId's bijgewerkt.

3. Geen objectId's of disciplineId's gespecificeerd in de body:

   • Als er geen objectId's of disciplineId's in de body worden gespecificeerd, worden alle onderliggende disciplineId's van de gehele aanvraag bijgewerkt.

4. Het betreft ALTIJD alleen de disciplineId’s van de betreffende netbeheerder.

5. Combinaties van bovenstaande scenario's zijn mogelijk in 1 verzoek.

Deze flexibiliteit in specificatie maakt het mogelijk om gerichte updates uit te voeren op verschillende niveaus van de aanvraag, afhankelijk van de verstrekte parameters in de body van het verzoek.

codevoorbeeld (curl):

curl -X GET\ 
-H "Authorization: Bearer [[accessToken]]"\ 
-H "Accept: application/json"\ 
-H "Content-Type: application/json"\ "//aanvraag/{aanvraagId}/aanvraagpdf"