API informatie en ondersteuning

Introductie van de API

Doel van de API: De API (Application Programming Interface) wordt gebruikt om een gestandaardiseerde verbinding tot stand te brengen tussen het zaaksysteem van de aanleverende organisatie en de database van het Register Externe Veiligheid. Dit stelt systemen in staat om automatisch gegevens uit te wisselen en processen te automatiseren, zonder menselijke tussenkomst of handmatige interactie via een webinterface (Aanleverportaal). Het primaire doel is om efficiëntie en nauwkeurigheid te bevorderen door real-time/ingeplande communicatie en gestroomlijnde workflows te faciliteren.
Voordelen: Het gebruik van een API biedt tal van voordelen, zoals procesautomatisering, waarmee menselijke fouten worden verminderd en verwerkingstijden worden versneld. API's zorgen voor consistente, veilige data-uitwisseling en zijn schaalbaar, waardoor ze geschikt zijn voor toekomstige uitbreiding. Bovendien kan dit op lange termijn kosten en tijd besparen door minder handmatige arbeid, terwijl de integratie met nieuwe technologieën en systemen eenvoudiger wordt gemaakt. Dit in het kader van de toekomstvisie rondom het REV.

De aanvraag voor API client(s) kan ingediend worden via het online formulier die te vinden is op Contact Register Externe Veiligheidsrisico's (REV) | Informatiepunt Leefomgeving
Aanleveren naam van de organisatie, KVK nummer en contactpersoon.
Zodra de aanvraag is ingediend streeft de afdeling Functioneel Beheer REV ernaar binnen 5 dagen het verzoek af te handelen.
U ontvangt dan een client ID en secret client, met een uitgebreide instructie voor het verkrijgen van een token en het opzetten van de JSON bestanden.
Omgevingsdiensten, lokale overheden en overige brondhouders ontvangen de gegevens voor zowel de Pre-productie als de Productie omgeving.
Softwareleveranciers ontvangen uitsluitend generieke gegevens voor de Pre-productieomgeving voor de opbouw van de verbinding en de gegevens uitwisseling door de klant.
Tip: het is aan te raden dat de gegevens aangevraagd worden door de opdrachtgever en dat deze de gegevens voor het opzetten van de verbinding doorspeelt naar de softwareleverancier.

Overzicht van beschikbare eindpunten, inclusief:
- HTTP-methoden (GET, POST, PUT, DELETE). (wordt binnenkort aangevuld)
- URL-structuur en parameters (path- en queryparameters). (wordt binnenkort aangevuld)
- Voorbeelden van requests en responses. (wordt binnenkort aangevuld)

Toelichting op statuscodes
HTTP-statuscodes worden gebruikt door webservers om de status van een verzoek te communiceren naar de client (bijvoorbeeld een browser of een API-gebruiker). Hier is wat de genoemde statuscodes betekenen:
- Statuscode 200: OK
  Betekenis: Het verzoek is succesvol verwerkt.
  Toepassing: Wordt meestal gebruikt wanneer een server succesvol een pagina of API-respons heeft geleverd.
- Statuscode 400: Bad Request
  Betekenis: Het verzoek van de client bevatte een fout en kan niet worden verwerkt door de server.
  Toepassing: Dit gebeurt vaak bij ongeldige of onjuiste invoer van gegevens.
  Voorbeeld: Een API-verzoek ontbreekt een verplichte parameter, of er is een syntaxfout in de query.
- Statuscode 401: Unauthorized
  Betekenis: De client is niet geauthentiseerd. Het verzoek vereist een geldige inlog of token.
  Toepassing: Treedt op als de client niet is ingelogd of verkeerde inloggegevens heeft gebruikt.
  Voorbeeld: Een gebruiker probeert toegang te krijgen tot een beveiligde API zonder een geldige toegangssleutel (API-key).
- Statuscode 500: Internal Server Error
  Betekenis: Er is een algemene fout op de server, vaak zonder verdere details.
  Toepassing: Dit wijst meestal op een programmeerfout, servercrash, of een onverwachte situatie die de server niet kan afhandelen.
  Voorbeeld: Een applicatie probeert een niet-bestaande functie op te roepen of een databaseverbinding faalt.

Er wordt uitsluitend gebruik gemaakt van het JSON gegevensformat.
Vereisten voor invoerdata en verwachte outputdata: op dit moment is het uitsluitend mogelijk om individuele JSON’s te uploaden.
Het is mogelijk om een individuele JSON aan te bieden aan het REV. Hiervoor is op het Aanleverportaal een upload portaal ontwikkeld. Deze kan eventueel worden gebruikt om te testen of de JSON goed is geconfigureerd.
Welke velden mogen of moeten voorkomen in het JSON bericht, en van welk datatype deze mogen zijn, is beschreven in de API specificatie die je kunt inzien via de Swagger documentatie:
Swagger IMEV 1.3 https://rev-portaal.nl/api-docs/swagger.html?url=https://rev-portaal.nl/oas/rev-v3-specification.yaml
Json schema IMEV 1.3 https://rev-portaal.nl/oas/imev13-schema.yaml
Swagger IMEV 2.0 https://rev-portaal.nl/api-docs/swagger.html?url=https://rev-portaal.nl/oas/rev-v4-specification.yaml
Json schema IMEV 2.0 https://rev-portaal.nl/oas/imev20-schema.yaml
Kijk voor meer informatie over de schema’s en wijzigingen op de volgende pagina: https://github.com/Geonovum/imev-werkomgeving/issues/101

Om het koppelvlak te testen is hier de eindpoint gegeven naar het test koppelvlak. https://preprod.rev-portaal.nl/api/rev/v4/
Voorbeelddata in de Oefenomgeving wordt periodiek bijgewerkt en kan wat verouderd zijn.

Belangrijk voor API gebruikers: schema voor het uitfaseren en API versies

REV API geldigheidsplanning:

V3 – geldig tot Eind februari 2025

V4 – geldigheid van mei 2024 t/m december 2025

V5 - geldigheid vanaf januari 2026

Wanneer u al in bezit bent van API gegevens en ondersteuning nodig heeft bij het in gebruik nemen ervan kunt u met ons contact opnemen via het IPLO. Ook kan er worden gemaild naar rev.fb@rws.nl.

LET OP:

Vermeld dat het over de API gaat en minimaal de volledige identificatie, om welke kaartlaag het gaat en tijdstip waarop het probleem heeft plaatsgevonden
Aanvullend kunnen de gegevens met de volgende informatie worden aangevuld:
- Beschrijving van het probleem:
  Welke functionaliteit werkt niet
  Is er een foutmelding en, zo ja, wat is de exacte tekst van de foutmelding
  Wat was de verwachting en wat gebeurt er.
- Betrokken API
  Naam, eindpunten en eventuele documentatie
- Technische gegevens van het verzoek die de API oproept
  Respons en Statuscode
- Logboeken (indien mogelijk)

Beschikbare naslagwerk en overige documentatie (wordt binnenkort aangevuld)
Gedurende 2024 en 2025 zal ook een externe leverancier door ons worden aangesproken voor extra ondersteuning bij het aansluiten op REV via de API koppelvlakken.