Technische documentatie

Basisdocumentatie voor API’s, integraties en technische afspraken. Deze pagina is volledig statisch (HTML/CSS) en kan je meteen deployen.

Tip: voeg later extra pagina’s toe (bv. auth.html, api.html) of stap over naar een generator (MkDocs / Docusaurus) als de scope groeit.

Quickstart

Maak een map en plaats index.html en styles.css erin.
Test lokaal of deploy als statische site (Azure Static Web Apps, App Service, Nginx, S3, …).
Vervang de voorbeeldsecties door de concrete North Sea Port API-informatie.

# lokaal testen (kies 1)
python -m http.server 8080
# of
npx serve .

Authenticatie

Documenteer hier het auth model (bv. OAuth2 Client Credentials, mTLS, API keys via API Management, …). Hieronder een voorbeeld met Bearer token.

Voorbeeld: Bearer token

curl -H "Authorization: Bearer <token>" \
  https://api.northseaport.example/v1/assets

Fouten & conventies

HTTP status codes: 2xx success, 4xx client errors, 5xx server errors
Correlation-ID: accepteer/return een X-Correlation-Id header
Problem Details: overweeg RFC7807 stijl

{
  "type": "https://northseaport.example/problems/validation",
  "title": "Validatiefout",
  "status": 400,
  "traceId": "00-2f3c...-01",
  "errors": [
    { "field": "portCallId", "message": "Verplicht veld." }
  ]
}

Base URL’s

Omgeving	Base URL
Test	`https://api-test.northseaport.example/v1`
Productie	`https://api.northseaport.example/v1`

Rate limits

Beschrijf hier de policy (bv. requests/minuut per client) en hoe clients limieten detecteren.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

GET /health

Eenvoudig liveness/readiness endpoint voor integraties en monitoring.

curl https://api.northseaport.example/v1/health

{
  "status": "ok",
  "time": "2026-02-10T12:00:00Z"
}

GET /assets

Voorbeeld endpoint om assets op te halen.

Query parameters

page (int)
pageSize (int)
type (string)

curl -H "Authorization: Bearer <token>" \
  "https://api.northseaport.example/v1/assets?page=1&pageSize=50&type=vessel"

{
  "items": [
    { "id": "a_123", "type": "vessel", "name": "Voorbeeld schip" }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

POST /events

Voorbeeld endpoint om events te pushen vanuit externe systemen.

Request

{
  "eventType": "PortCallUpdated",
  "occurredAt": "2026-02-10T12:00:00Z",
  "data": {
    "portCallId": "PC-2026-000123",
    "status": "ARRIVED"
  }
}

Response

{
  "accepted": true,
  "eventId": "evt_9f3a1c"
}

Webhooks

Definieer callback URLs, signature verification, retries en dead-lettering.

Best practice: signeer payloads (bv. HMAC) en documenteer replay protection.

Idempotency

Voor POST/PUT: ondersteun een Idempotency-Key header zodat retries geen duplicaten veroorzaken.

Idempotency-Key: 2b8f5c26-9d1d-4d8c-bb83-0f2d9d2d9a12

Versies & migraties

Versies in path: /v1, /v2
Deprecation policy met concrete data’s
Changelog per release

Observability

Log/trace afspraken: correlation IDs, structured logging, metrics en dashboards.

Security

TLS only
Least privilege scopes/rollen
IP allowlisting (indien relevant)
Audit logging voor gevoelige acties

Support

Vul hier je support model in (SLA, contactpunten, escalatiepad).

Changelog

2026-02-10 Initieel documentatieplatform