API registratie

API van het API register (apis.developer.overheid.nl)

Overview

• API version: 1.0.0
• Build date: 2025-04-02
• Generator version: 7.7.0

Lokaal draaien

1. Start de afhankelijkheden:

   docker compose up -d
   

2. Start de server:

   go run cmd/main.go
   

   De API luistert standaard op poort 1337.

Logging in Loki en Grafana

De applicatie schrijft gestructureerde JSON-logs naar stdout. Loki kan daardoor het veld level als detected_level herkennen. Het standaardniveau is info; stel LOG_LEVEL in op debug, info, warn of error om de ondergrens aan te passen.

Iedere applicatielog bevat vaste zoekvelden:

• app: altijd api-register, zodat iedere regel direct naar deze applicatie te herleiden is;
• level: de severity (DEBUG, INFO, WARN of ERROR);
• component: het functionele onderdeel, zoals oas_refresh, tools of typesense;
• operation: de handeling binnen het onderdeel;
• waar relevant api_id, source, artifact_id, aantallen en error.

Velden met veel verschillende waarden, zoals api_id, horen niet als permanente Loki-labels te worden ingericht. Parse ze tijdens de query om hoge cardinaliteit te voorkomen. Voorbeelden:

{app="api-register"} | detected_level="error" | json
{app="api-register"} | json | component="oas_refresh" | api_id="<api-id>"
{app="api-register"} | json | component="harvest" | source="pdok"

Typesense integratie

Nieuwe APIs worden na een succesvolle POST ook naar Typesense gestuurd, zodat ze vindbaar zijn in de zoekfunctie. Stel hiervoor de volgende omgevingsvariabelen in:

• TYPESENSE_ENDPOINT: basis-URL van de Typesense cluster (bijv. https://search.don.apps.digilab.network).
• TYPESENSE_API_KEY: API key met schrijfrechten.
• TYPESENSE_COLLECTION: naam van de collectie (standaard api_register).
• TYPESENSE_DETAIL_BASE_URL: basis-URL voor detailpagina's in de frontend (bijv. https://api-register.don.apps.digilab.network/apis).
• ENABLE_TYPESENSE: zet op false om Typesense indexing volledig uit te schakelen (standaard true).

Dagelijkse OAS-refresh

Bij het opstarten van de server wordt automatisch een aparte service gestart die direct een refresh-run uitvoert. Daarna draait de job iedere ochtend om 07:00 en haalt alle geregistreerde APIs opnieuw op. Zodra de OAS is gewijzigd, volgen exact dezelfde stappen als bij een POST: validatie, regeneratie van artifacts (Postman en OAS-bestanden) en het opruimen van verouderde bestanden. Er zijn geen extra omgevingsvariabelen nodig.

RSS-feed configuratie

Elke API heeft een RSS-feed beschikbaar op /apis/{id}/feed.rss.

Changelog (Changie)

Voor user-facing wijzigingen (fix/feature/breaking) verwachten we per PR een Changie-fragment in .changes/unreleased.

Eenmalig installeren:

go install github.com/miniscruff/changie@latest

Fragment aanmaken:

changie new

Normaal is een fragment niet nodig voor interne refactors zonder zichtbaar effect, docs-only wijzigingen en CI-only tweaks.

Bij een release kun je de fragments bundelen in CHANGELOG.md:

changie batch <version>

Dit gebeurt ook automatisch bij elke merge naar main via GitHub Actions: changie batch auto en daarna changie merge, waarna automatisch een PR met de changelog-updates wordt aangemaakt.

Deployen

De deployment van deze site verloopt via GitHub Actions en een aparte infra repository.

Benodigde variabelen en secrets

• Organization variable INFRA_REPO, bijvoorbeeld developer-overheid-nl/don-infra.
• Repository variable KUSTOMIZE_PATH, met als basispad bijvoorbeeld apps/api/overlays/.
• Secrets RELEASE_PROCES_APP_ID en RELEASE_PROCES_APP_PRIVATE_KEY voor het aanpassen van de infra repository.

Deploy naar test

De testdeploy draait via .github/workflows/deploy-test.yml.

• De workflow draait op pushes naar branches behalve main.
• Alleen commits met [deploy-test] in de commit message worden echt gedeployed.
• Er wordt een image gebouwd en gepusht naar ghcr.io/<owner>/<repo> met tags test en de commit SHA.
• Daarna wordt in INFRA_REPO het bestand ${KUSTOMIZE_PATH}test/kustomization.yaml bijgewerkt naar de nieuwe image tag en direct gecommit.

Voorbeeld commit message:

feat: pas content aan [deploy-test]

Deploy naar productie

De productiedeploy draait via .github/workflows/deploy-prod.yml.

• De workflow draait bij een push naar main.
• Er wordt in INFRA_REPO een release branch aangemaakt.
• In ${KUSTOMIZE_PATH}prod/kustomization.yaml wordt de image tag bijgewerkt naar de commit SHA van deze repository.
• Daarna wordt automatisch een pull request in de infra repository geopend.
• De productie-uitrol gebeurt door die pull request te mergen.

Contributies en deploy

Een contribution of pull request leidt niet automatisch tot een deployment.

• Een pull request triggert wel CI, waaronder de build en JSON-validatie.
• De build in .github/workflows/go-ci.yml bouwt voor een pull request een Docker image als controle, maar pusht dat image niet naar GHCR en past de infra repository niet aan.
• Er is dus geen automatische preview-omgeving per pull request.
• Een testdeploy gebeurt pas na een push naar een branch in deze repository met [deploy-test] in de commit message.
• Die testdeploy gebruikt repository- en organization-variables en secrets om ook INFRA_REPO aan te passen. Daardoor is dit pad in de praktijk bedoeld voor maintainers of contributors met een branch in deze repository.