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 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 en een melding op deze pagina en in 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.

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 · API-documentatie · OpenAPI

Fokuus