API voor opslag en ontsluiting van documenten en daarbij behorende metadata.
De API ondersteunt het opslaan en naar andere applicaties ontsluiten van informatieobjecten (in de ‘volksmond’: documenten). De component slaat deze gestructureerd en voorzien van de benodigde metadata op en stelt applicaties in staat deze te wijzigen, te verwijderen en aan de hand van een aantal zoekcriteria op te vragen. Opslag vindt plaats conform het informatie-objecten-gedeelte van het RGBZ.
Een informatieobject is een generiekere term voor het veelgebruikte begrip document dat beperkter van reikwijdte is.
Een informatieobject kan van alles zijn, ongeacht aard en vorm: een tekstverwerkingsdocument, een papieren brief, een webpagina, een landkaart, een foto, een geluidsopname, een dataset, een blog, etc.
Vooralsnog ondersteunt de Documenten API alleen enkelvoudige informatieobjecten. Een e-mail met drie bijlagen of een verzoek met bijbehorende CAD-tekening en Excel spreadsheet kan worden beschouwd als een samengesteld informatieobject. Mogelijk dat dit objecttype in de toekomst nog wordt toegevoegd aan deze API.
Een informatieobject kan tot meer dan één zaak behoren en een zaak kan meer dan één informatieobjecten bevatten. De relatie tussen zaak en informatieobject is vastgelegd in zaakinformatieobject (Zaken API) en objectinformatieobject (Documenten API), waarbij zaakinformatieobject leidend is.
Een besluit kan vastgelegd zijn in een informatieobject. De relatie tussen besluit en informatieobject is vastgelegd in besluitinformatieobject (Besluiten API) en objectinformatieobject (Documenten API), waarbij besluitinformatieobject leidend is.
In versie 1.0.x van de API moet het bestand base64-encoded opgeslagen worden in het attribuut inhoud
. De omvang mag 4GB groot zijn. Hou hierbij rekening met de overhead van base64, die, in worst-case scenario’s, ongeveer 33% bedraagt . Dit betekent dat bij een limiet van 4GB het bestand maximaal ongeveer 3GB groot mag zijn.
Uploaden van bestanden
Binnen deze API bestaan een aantal endpoints die binaire data ontvangen, al dan niet base64-encoded. Webservers moeten op deze endpoints een minimale request body size van 4.0 GiB ondersteunen. Dit omvat de JSON van de metadata EN de base64-encoded bestandsdata. Hou hierbij rekening met de overhead van base64, die ongeveer 33% bedraagt in worst-case scenario’s. Dit betekent dat bij een limiet van 4GB het bestand maximaal ongeveer 3GB groot mag zijn.
Nieuw in versie 1.1.0
Bestanden kunnen groter zijn dan de hierboven genoemde 3GB. In dat geval is het mogelijk om het bestand in delen op te splitsen en in delen toe te voegen. Om dit te doen moet de consumer:
De 1.0.x manier van uploaden is ook beschikbaar voor kleine(re) bestanden die niet gesplitst hoeven te worden. Het is echter niet verplicht om deze manier te blijven gebruiken voor bestanden kleiner dan 3GB. Ook dan mag de hierboven beschreven manier met bestandsdelen gebruikt worden.
Nieuw in versie 1.1.0 Afhankelijk van de omvang van het bestand wordt de inhoud van het informatieobject als volgt opgeslagen:
inhoud
blijft leeginhoud
.bestandsdelen
Alle informatieobjecten van de zaak vormen het zaakarchief, de informatieobjecten en zaakkenmerken samen vormen het zaakdossier.
Nieuw in versie 1.1.0 Een verzoek kan onderbouwd worden met één of meer informatieobjecten. De relatie tussen verzoek en informatieobject is vastgelegd in verzoekinformatieobject (Verzoeken API) en objectinformatieobject (Documenten API), waarbij verzoekinformatieobject leidend is.
Nieuw in versie 1.2.0 De relatie klasse Verzending legt vast aan welke Betrokkene een Informatieobject verzonden is of van welke Betrokkene een Informatieobject ontvangen is. Om altijd te kunnen achterhalen naar/van welk adres een Informatieobject verzonden of ontvangen is moet dit adres ook worden vastgelegd. Immers, wanneer alleen verwezen wordt naar het adres waarop iemand ingeschreven staat verandert dit gegeven wanneer deze persoon verhuist of de geregistreerde gegevens bijgewerkt worden. Door het adres vast te leggen in Verzending is altijd te achterhalen naar/van welk adres een Informatieobject verstuurd/ontvangen is.
Een Enkelvoudiginformatieobject
kan meer dan één maal verzonden worden maar een Verzending
is altijd slechts naar één adres
. De waarde van aardrelatie
is dan geadresseerde
. Onder een adres
wordt verstaan één van onderstaande gegevens:
Het is dus niet mogelijk om in een Verzending
bijvoorbeeld zowel een emailadres
als mijnOverheid
of een correspondentiePostadres
aan te geven, dit zijn immers meerdere adressen. In dat geval dienen evenzovele Verzendingen
aangemaakt te worden als er verschillende adressen gebruikt zijn.
Een Enkelvoudiginformatieobject
kan ook slechts van één adres ontvangen worden. De waarde van aardrelatie
is dan afzender
. Wanneer een Informatieobject ontvangen en geregistreerd wordt zal dit informatieobject als nieuw informatieobject geregistreerd worden. Daarom zal de relatie tussen een Enkelvoudiginformatieobject
en een Verzending
in geval van ontvangen (en er dus een afzender geregistreerd wordt) een 1 op 1 relatie zijn.
Het attribuut richting
uit de relatieklasse ZaaktypeInformatieobjecttype en de attributen ontvangstdatum
en verzenddatum
uit Einkelvoudiginformatieobject zijn hiermee overbodig en deprecated geworden.
Referentie-implementatie Documenten API
De releasenotes van de versies staan beschreven op deze pagina
Versie | Releasedatum | API specificatie |
---|---|---|
1.5.0 | 14-03-2024 | ReDoc, Swagger |
1.4.3 | 27-10-2023 | ReDoc, Swagger |
1.4.2 | 26-09-2023 | ReDoc, Swagger |
1.3.2 | 26-09-2023 | ReDoc, Swagger |
1.2.5 | 26-09-2023 | ReDoc, Swagger |
1.4.1 | 29-08-2023 | ReDoc, Swagger |
1.3.1 | 29-08-2023 | ReDoc, Swagger |
1.2.4 | 29-08-2023 | ReDoc, Swagger |
1.4.0 | 22-08-2023 | ReDoc, Swagger |
1.3.0 | 29-03-2023 | ReDoc, Swagger, Diff |
1.2.0 | 19-12-2022 | ReDoc, Swagger, Diff |
1.1.0 | 24-05-2021 | ReDoc, Swagger, YAML, JSON, Diff |
1.0.1 | 2019-12-16 | ReDoc, Swagger, YAML, Diff |
1.0.0 | 2019-11-18 | ReDoc, Swagger |
Documenten APIsen (DRC) MOETEN aan twee aspecten voldoen:
de DRC openapi.yaml
MOET volledig geïmplementeerd zijn.
het run-time gedrag beschreven in deze standaard MOET correct geïmplementeerd zijn.
Alle operaties beschreven in openapi.yaml
MOETEN ondersteund worden en tot hetzelfde resultaat leiden als de referentie-implementatie van het DRC.
Het is NIET TOEGESTAAN om gebruik te maken van operaties die niet beschreven staan in deze OAS spec, of om uitbreidingen op operaties in welke vorm dan ook toe te voegen.
Bepaalde gedrageningen kunnen niet in een OAS spec uitgedrukt worden omdat ze businesslogica bevatten. Deze gedragingen zijn hieronder beschreven en MOETEN zoals beschreven geïmplementeerd worden.
Gewijzigd in 1.3.0
informatieobjecttype
op de EnkelvoudigInformatieObject
-resource (drc-001)Bij het aanmaken (enkelvoudiginformatieobject_create
) of bewerken (enkelvoudiginformatieobject_update
, enkelvoudiginformatieobject_partial_update
) MOET de URL-referentie naar het informatieobjecttype
gevalideerd worden op het bestaan. Indien het ophalen van het informatieobjecttype niet (uiteindelijk) resulteert in een HTTP 200
status code, MOET het DRC antwoorden met een HTTP 400
foutbericht.
De provider MOET tevens valideren dat het opgehaalde informatieobjecttype een informatieobjecttype is conform de geldige Catalogi API specificatie.
overgenomen uit de openapi.yaml
Daarnaast MOET de provider valideren dat het opgehaalde ‘informatieobjecttype’ ‘concept = false’ is. Indien het opgehaalde ‘informatieobjecttype’ niet ‘concept = false’ is MOET de DRC antwoorden met een HTTP 400
foutbericht.
object
op de ObjectInformatieObject
-resource (drc-002)Bij het aanmaken (objectinformatieobject_create
) MOET de URL-referentie naar het object
gevalideerd worden op het bestaan. Indien het ophalen van het object niet (uiteindelijk) resulteert in een HTTP 200
status code, MOET het DRC antwoorden met een HTTP 400
foutbericht.
(TODO: valideren dat het van het type object_type
is -> validatie aanscherpen)
object
en informatieobject
op de ObjectInformatieObject
-resource (drc-003)Er MOET gevalideerd worden dat de combinatie object
en informatieobject
niet eerder voorkomt. Indien deze al bestaat, dan MOET het DRC antwoorden met een HTTP 400
foutbericht.
object
en informatieobject
in de bron (drc-004)Er MOET gevalideerd worden dat de relatie tussen het object
en het informatieobject
al bestaat in de bron van het object
. De bron van het informatieobject is bekend door de eerdere validaties op deze URL. De API-spec van het bron register voorziet in query-parameters om het bestaan te kunnen valideren.
Wanneer InformatieObject.ontvangstdatum
een waarde heeft, dan zijn de waarden in bewerking
en ter vaststelling
voor InformatieObject.status
NIET TOEGESTAAN. Indien een dergelijke status gezet is voor de verzenddatum opgegeven wordt, dan moet de API een HTTP 400 foutbericht geven met status
als veld in de invalid-params
. De client MOET dan ontvangstdatum
leeg laten of eerst de status wijzingen.
Indien er geen gebruiksrechtenvoorwaarden van toepassing zijn op een informatieobject, dan moet InformatieObject.indicatieGebruiksrechten
op de waarde false
gezet worden. Indien de voorwaarden (nog) niet bekend zijn, dan moet de indicatie op null
gezet worden.
Om de indicatie op true
te zetten, MOET je de resource Gebruiksrechten
aanmaken in de API. Providers MOETEN bij het aanmaken van gebruiksrechten voor een informatieobject de indicatieGebruiksrechten
van dat informatieobject op true
zetten.
Indien de laatste gebruiksrechten op een informatieobject verwijderd worden, dan MOET de indicatie weer op null
gezet worden.
Indien de client een vertrouwelijkheidaanduiding
meegeeft bij het aanmaken of bewerken van een informatieobject, dan MOET de provider deze waarde toekennen. Indien de client deze niet expliciet toekent, dan MOET deze afgeleid worden uit InformatieOject.InformatieObjectType.vertrouwelijkheidaanduiding
.
Een InformatieOject
response van de provider MOET altijd een geldige waarde voor vertrouwelijkheidaanduiding
bevatten. Een client MAG een waarde voor vertrouwelijkheidaanduiding
meesturen.
Vernietigen van informatieobjecten (drc-008)
Een EnkelvoudigInformatieObject
MAG ALLEEN verwijderd worden indien er geen ObjectInformatieObject
-en meer aan hangen. Indien er nog relaties zijn, dan MOET het DRC antwoorden met een HTTP 400
foutbericht
Bij het verwijderen van een EnkelvoudigInformatieObject
MOETEN het EnkelvoudigInformatieObject
en gerelateerde objecten daadwerkelijk uit de opslag verwijderd worden. Zogenaamde “soft-deletes” zijn NIET TOEGESTAAN. Onder gerelateerde objecten wordt begrepen:
gebruiksrechten
- de gebruiksrechten die horen bij het EnkelvoudigInformatieObject
.audittrail
- de geschiedenis van het object.Bij het bijwerken van InformatieObject
(enkelvoudiginformatieobject_update
, enkelvoudiginformatieobject_partial_update
) MOET eerst een lock
verkregen worden. De consumer voert de enkelvoudiginformatieobject_lock
operatie uit, waarbij het DRC MOET antwoorden met een niet-te-raden lockId
. Het DRC MOET vervolgens alle schrijf-operaties blokkeren tenzij het correcte lockId
meegegeven is.
Het DRC MOET geforceerd unlocken toelaten door ‘administrators’. Dit zijn applicaties die de scope documenten.geforceerd-unlock
hebben. Deze consumers MOETEN het lockId
weglaten indien ze geforceerd unlocken.
overgenomen uit de openapi.yaml
Bij het werken wordt gevalideerd of:
gewijzigd in 1.4.0
gewijzigd in 1.3.0
Wanneer aan één of meer van deze voorwaarden niet wordt voldaan MOET het DRC antwoorden met een HTTP 400
foutbericht.
toegevoegd in 1.4.0
Indien een verzoek één of meer expand parameters bevat MOET deze parameter alleen informatie uit de Documenten API of gerelateerde informatie uit de Catalogi API bevatten. Indien een expand parameter om informatie uit andere bronnen vraagt moet een foutmelding (http 406?) worden teruggegeven.
Indien een verzoek één of meer expand parameters bevat MOET de expand niet dieper gaan dan maximaal 3 niveaus diep. Wanneer een consumer een diepere expand opgeeft MOET het antwoord maximaal de 3 niveaus diep gaan. Hiermee kan de volgende informatie in een response opgenomen worden:
Enkelvoudiginformatieobject
....
informatieobjectype
...
omschrijvingGeneriek
informatieobjecttypeOmschrijvingGeneriek
Indien een verzoek één of meer expand parameters bevat MOET het attribuut onderdeel zijn van de opgevraagde resource. Indien een expand parameter geen geldig attribuut is van de opgevraagde resource moet een foutmelding (http 404) worden teruggegeven.
Op een verzoek MOET een geldige response zoals deze opgevraagd is opleveren. Indien een verzoek één of meer expand parameters bevat MOET ook de te expanderen informatie opgehaald en teruggegeven kunnen worden. Indien geen geldige response kan worden teruggegeven moet een foutmelding (http 404) worden teruggegeven.
Nieuw in versie 1.1.0
De Documenten API moet HTTP-Caching ondersteunen op basis van de ETag
header. In de API spec staat beschreven voor welke resources dit van toepassing is.
De ETag
MOET worden berekend op de JSON-weergave van de resource. Verschillende, maar equivalente weergaves (bijvoorbeeld dezelfde API ontsloten wel/niet via NLX) MOETEN verschillende waarden voor de ETag
hebben.
Indien de consumer een HEAD
verzoek uitvooert op deze resources, dan MOET de provider antwoorden met dezelfde headers als bij een normale GET
, dus inclusief de ETag
header. Er MAG GEEN response body voorkomen.
Indien de consumer gebruik maakt van de If-None-Match
header, met één of meerdere waarden voor de ETag
, dan MOET de provider antwoorden met een HTTP 304
bericht indien de huidige ETag
waarde van de resource hierin voorkomt. Als de huidige ETag
waarde hier niet in voorkomt, dan MOET de provider een normale HTTP 200
response sturen.