API-documentatie
OpenAPI-specificatie (Swagger)
Standaardformaat om RESTful API's te beschrijven. De voordelen:
- Interactieve documentatie: Swagger UI om API's in de browser te testen
- Codegeneratie: Client-SDK's en serverstubs automatisch genereren
- API-validatie: Requests en responses valideren tegen het schema
- Contract-first ontwikkeling: De API-specificatie ontwerpen vóór de implementatie
Best practices voor documentatie
Volledige documentatie
- Duidelijke operatiebeschrijvingen die uitleggen wat elk endpoint doet
- Voorbeelden van requests en responses voor elke bewerking
- Foutcodes en hun betekenis
- Vereisten voor authenticatie en autorisatie
- Rate-limitingbeleid en quota
- Uitfaseringsberichten en migratiegidsen
- Codevoorbeelden in meerdere talen
- Aan-de-slaggids en tutorials
API-versiebeheer
Laat uw API evolueren zonder bestaande clients te breken. Gangbare strategieën:
Versies doorheen de tijd
202520262027
v1
v2
v3
PreviewAlgemeen beschikbaarUitgefaseerd
Clientverkeer per versie
v1
100%
v2
0%
v3
0%
v1 is de enige stabiele versie; v2 staat in preview bij de eerste gebruikers.
GET /v1/customers/1042
HTTP/1.1 200 OK
Content-Type: application/json
Illustratief voorbeeld
Versiebeheer via de URI
Versie in het URL-pad: /v1/customers, /v2/customers
Voordelen: Eenvoudig, expliciet, makkelijk te routeren
Versiebeheer via een header
Versie in een eigen header: X-API-Version: 2 of Accept: application/vnd.company.v2+json
Voordelen: Zuivere URI's, ondersteunt content negotiation
Versiebeheer via een queryparameter
Versie in de querystring: /customers?version=2
Voordelen: Eenvoudig te implementeren, ondersteunt een standaardversie
Best practices voor versiebeheer
- Maak alleen een nieuwe versie bij breaking changes
- Ondersteun minimaal N-1 versies (huidige en vorige)
- Communiceer de uitfaseringstermijnen duidelijk
- Gebruik intern semantic versioning (major.minor.patch)
- Toon in de publieke API alleen de hoofdversie