Woo-API

Let op: de Woo-API is nog niet in productie.
Tot nader bericht is het voor bestuursorganen nog niet
mogelijk om contactpersonen of gebruikersaccounts aan
te melden.

Introductie

Als overheid kunt u de API (application programming interface) gebruiken om uw lokale systemen aan te sluiten op de generieke Woo-voorziening om informatie uit te wisselen. Bijvoorbeeld om documenten en metadata op open.overheid.nl actief openbaar te maken, maar ook voor het wijzigen van al eerder opgestuurde. Op deze pagina wordt beschreven hoe een organisatie kan aansluiten op de API.

Voorbereiding

Vanuit uw eigen systeem (/systemen) moet een systeemkoppeling gerealiseerd worden. Benader hiervoor uw ICT afdeling of externe leverancier(s). De voorbereidende activiteiten bij de bestuursorganen vallen onder de verantwoordelijkheid van de organisaties zelf. Op deze pagina staat beschreven hoe u de benodigde client credentials kan aanvragen voor de API. Daarnaast zijn de volgende producten aanwezig ter voorbereiding op het aansluiten op de API:

Open API Specificatie (OAS)
Functionele beschrijving AO Rijk API
Jason bestand voorbeeld
Veelgestelde vragen (verderop deze pagina)
Test-omgeving (verderop deze pagina)
Ondersteuning (verderop deze pagina)

Let op: Vooralsnog vragen we u alleen documenten te publiceren die openbaar gemaakt moeten worden na 1 april 2025. Het publiceren van documenten met terugwerkende kracht van voor deze datum vragen we u vooralsnog mee te wachten

Stappenplan bestuursorgaan

Onderstaande stappen dienen te worden gevolgd:

Stappenplan
Voorbereiding	(STAP 1) Meld een contactpersoon aan voor uw bestuursorgaan en vraag als contactpersoon client credentials aan (STAP 2) Ontvang de client credentials in uw e-mailbox
Testen	(STAP 3) Test eerst de connectiviteit en zorg voor een eerste publicatie op de test-omgeving van KOOP alvorens u gaat publiceren op de productie-omgeving.
Publiceren op productie	(STAP 4) Na een succesvolle test op de acceptatie-omgeving van KOOP kan uw organisatie starten met openbaar maken van documenten op de productie-omgeving

Toegang tot de API

Authenticatie

Authenticatie geschiedt via client credentials. Hoe dit in zijn werk gaat staat uitgelegd in de Functionele beschrijving AO Rijk API.

Aanmelden contactpersoon + aanvragen client credentials

Contactpersonen kunnen worden aangemeld door een tekenbevoegde vertegenwoordiger of een ander contactpersoon aan te melden.
Het onderstaande formulier dient ingevuld en ondertekend te worden opgestuurd naar woo@koop.overheid.nl

Formulier I Woo API aanmelding en wijziging Contactpersoon

De credentials worden gestuurd naar het e-mail-adres van het opgegeven contactpersoon. U ontvangt client credentials voor zowel de productie-omgeving als de test-omgeving. Ook wordt de endpoint informatie hier in opgenomen.

Wat wordt verwacht van de contactpersoon?

Als contactpersoon bent u namens uw organisatie het aanspreekpunt voor KOOP en voor de gebruikers binnen uw organisatie. Het volgende wordt verwacht van een contactpersoon:

Het informeren van de eigen organisatie over wijzigingen rondom het aanleverloket en/of de API
Het aanvragen van client credentials ten behoeve van de API
De client credentials al dan niet te delen met uw externe leverancier.
Het communiceren van verstoringen of updates
Binnen uw organisatie aanspreekpunt voor KOOP

Test-omgeving

De test-omgeving is een omgeving voor ontwikkelaars die gebruik maken van de AO Rijk API. Het gaat om ontwikkelaars van leveranciers die een dienst willen aanbieden en ontwikkelaars van overheidsorganisaties die documenten actief openbaar moeten gaan maken. De ontwikkelaars kunnen deze omgeving gebruiken voor voorbereidende technische testen. Een set client-credentials voor deze omgeving worden verstrekt met bij credentials van de productie-omgeving. Hieronder nog wel een aantal aandachtspunten en spelregels voor de test-omgeving:

Aandachtspunten:

De testomgeving is geen ketentest-omgeving.
De maximale bestandsgrootte is 1mb
De testomgeving is niet bedoeld om performancetesten of stresstesten te initiëren.

Fair use Policy

Er zijn geen kosten verbonden aan het gebruik. Bij (ogenschijnlijk) verkeerd gebruik of misbruik van de testomgeving zal KOOP contact opnemen met de betreffende organisatie en in het uiterste geval de toegang intrekken. KOOP neemt contact op als:

er vermoeden is van onwettige activiteiten;
KOOP constateert dat de testomgeving structureel zo zwaar wordt belast dat andere gebruikers of KOOP daar substantiële hinder van ondervinden.

End-point informatie

De end-points van zowel de test-omgeving als productie-omgeving worden meegestuurd met de client-credentials.

Documentopslag

Documenten aangeleverd door ministeries worden opgeslagen bij Logius KOOP.

Veelgestelde vragen

De API ondersteund de bestandsformaten PDF en ZIP.

Aandachtspunt voor ZIP-bestanden:

Alle documenten die in een ZIP worden aangeleverd, worden samen gezien als een geaggregeerd document. Dit telt voor de API als 1 document. Zip-bestanden worden niet automatisch uitgepakt maar zullen zonder verdere verwerking weergegeven worden op het portaal, als downloadbaar bestand. De metadata horen bij het ZIP-bestand als geheel, de daarin opgenomen losse documenten hebben geen eigen metadata.

Documenten staan regelmatig niet op zichzelf. Er horen andere documenten bij. Denk hierin bijvoorbeeld aan dossiers, collecties, bundelingen, bijlagen, zaken (vanuit zaaksystemen), etc.. Bij het aanleveren van documenten aan de API kunnen deze verbanden worden aangegeven. Dat worden aggregaties genoemd.

Er zijn vooralsnog 3 afzonderlijke manieren waarop een verband (aggregatie) kan worden aangegeven:

gemeenschappelijk kenmerk
bestandsformaat ZIP
relaties tussen documenten documenten leggen
In de Functionele beschrijving AO Rijk API wordt dit verder toegelicht.

Ondersteuning

Al uw functionele en technische vragen over het aansluiten op de generieke Woo-voorziening kunt u stellen via woo@koop.overheid.nl. KOOP verzorgt ook diverse online informatiebijeenkomsten en invulsessies over de Woo-index en de technische aanlevermogelijkheden. Kijk hiervoor op de bijeenkomsten pagina.