# Fokuus API-versiebeleid en uitfasering

Hoe de publieke Fokuus API, MCP-server en NLWeb-zoekfunctie versies krijgen, wat zonder aankondiging kan veranderen en hoe we uitfasering minstens 90 dagen vooraf melden.

## Huidige versies

- REST-API v1 op `https://fokuus.be/api/v1`: stabiel sinds 21 september 2026. Het [OpenAPI-document](https://fokuus.be/openapi.json)  heeft versie 1.0.0.
- MCP-server `fokuus-public-information` 1.0.0 op `https://fokuus.be/mcp`, met de MCP-protocolversies 2025-11-25, 2025-06-18 en 2025-03-26.
- NLWeb-zoekfunctie `/ask` volgens NLWeb 0.55.

Er is momenteel geen enkele versie uitgefaseerd.

## Wat binnen v1 kan veranderen

Nieuwe velden in een antwoord, nieuwe endpoints, nieuwe optionele parameters, nieuwe MCP-tools en nieuwe pagina’s in de catalogus. Die wijzigingen breken niets. Negeer velden die je niet kent.

## Wat een nieuwe hoofdversie vraagt

Een veld of endpoint verwijderen of hernoemen, een type wijzigen of strengere validatie invoeren. Zo’n wijziging komt in een nieuw pad, zoals `/api/v2`. Bij de MCP-server krijgt een gewijzigde tool een nieuwe naam. De vorige versie blijft minstens 90 dagen na de aankondiging werken.

## Zo kondigen we uitfasering aan

- De header `Deprecation` (RFC 9745) met de uitfaseringsdatum, op elk antwoord van de betrokken versie.
- De header `Sunset` (RFC 8594) met de datum waarop de versie stopt, minstens 90 dagen na de aankondiging.
- Een `Link`-header met `rel="deprecation"` en `rel="sunset"` naar deze pagina. Die staat nu al op elk API-antwoord.
- `deprecated: true` in de [OpenAPI-specificatie](https://fokuus.be/openapi.json)  en een melding op deze pagina en in [llms.txt](https://fokuus.be/llms.txt) .

Na de einddatum antwoordt een stopgezette versie met 410 Gone en een JSON-fout die naar de opvolger verwijst.

## Limieten

Het quotabeleid staat op elk antwoord in `RateLimit-Policy`: 120 verzoeken per 60 seconden per IP-adres. Wijzigt dat beleid, dan zie je dat in die header en in de [API-documentatie](https://fokuus.be/docs/) .

## Wijzigingslog

- Oktober 2026: `RateLimit-Policy` op elk antwoord, 429 met `Retry-After` en `RateLimit`, en `Link`-verwijzingen naar dit beleid. Uitbreiding, geen actie nodig.
- 21 september 2026: REST-API v1, MCP-server en NLWeb-zoekfunctie gepubliceerd.

[Developerstart](https://fokuus.be/developers/)  · [API-documentatie](https://fokuus.be/docs/)  · [OpenAPI](https://fokuus.be/openapi.json)

[Bron](https://fokuus.be/docs/versioning/) · [Agentdocumentatie](https://fokuus.be/developers/)