Uitwisselingsformaten en -protocollen on Leerlijnen KCA

4.0 Todo voor Uitwisselformaten

Wed, 04 Mar 2026 00:00:00 +0000

1.0 Todo-lijst voor Uitwisselformaten

Nr	Wie	Wat
01	Johan	Todo-lijst vullen

4.1 XML als uitwisselingsformaat

Wed, 04 Mar 2026 00:00:00 +0000

4.1 XML als uitwisselingsformaat

Kent XML als uitwisselingsformaat (structuur, syntax, schema’s).

Wat is XML?

XML (eXtensible Markup Language) is een markup-taal ontworpen voor het opslaan en transporteren van gestructureerde data. In de overheidscontext is XML de ruggengraat van vele uitwisselingstandaarden, waaronder StUF (Standaard Uitwisseling Formaat).

Kernprincipes van XML:

Self-describing: Data en structuur in één formaat
Human-readable: Leesbaar voor mensen én machines
Platform-independent: Werkt op alle systemen
Extensible: Flexibel uitbreidbaar voor specific behoeften

XML-structuur en syntax

Basis XML-elementen

<?xml version="1.0" encoding="UTF-8"?>
<BRP:Persoon xmlns:BRP="http://www.stufstandaarden.nl/basisgegevens">
 <BRP:BSN>123456789</BRP:BSN>
 <BRP:Geslachtsnaam>
 <BRP:Voorvoegsel>van der</BRP:Voorvoegsel>
 <BRP:GeslachtsnaamStam>Berg</BRP:GeslachtsnaamStam>
 </BRP:Geslachtsnaam>
 <BRP:Voornamen>Jan Peter</BRP:Voornamen>
 <BRP:Geboortedatum>1985-03-15</BRP:Geboortedatum>
</BRP:Persoon>

Syntax-regels

Case-sensitive: <Persoon> ≠ <persoon>
Well-formed: Elke opening-tag heeft matching closing-tag
Nested structure: Elementen kunnen elementen bevatten
Attribute syntax: <element attribuut="waarde">

Namespaces

<!-- Namespace declaraties -->
<StUF:Bv03Bericht
 xmlns:StUF="http://www.stufstandaarden.nl/koppelvlak/stuf"
 xmlns:BG="http://www.stufstandaarden.nl/onderlaag/bg"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

 <StUF:stuurgegevens>
 <StUF:berichtCode>Lv01</StUF:berichtCode>
 <StUF:zender>
 <StUF:organisatie>0363</StUF:organisatie>
 </StUF:zender>
 </StUF:stuurgegevens>
</StUF:Bv03Bericht>

XML Schema’s (XSD)

XML Schema Definition (XSD) definieert de structuur, elementen en datatypes van XML-documenten.

4.2 JSON als uitwisselingsformaat

Wed, 04 Mar 2026 00:00:00 +0000

4.2 JSON als uitwisselingsformaat

Kent JSON als modern uitwisselingsformaat (syntax, schema’s, voordelen ten opzichte van XML).

Wat is JSON?

JSON (JavaScript Object Notation) is een lichtgewicht, text-based data-uitwisselingsformaat. Hoewel oorspronkelijk ontworpen voor JavaScript, is JSON nu de de-facto standaard geworden voor moderne web-APIs en wordt steeds vaker ingezet in overheidscontext als alternatief voor XML.

Kerneigenschappen:

Compact: Minder overhead dan XML
Human-readable: Eenvoudig te lezen en schrijven
Native JavaScript: Perfect voor web-applicaties
Language-agnostic: Support in alle moderne programmeertalen

JSON-syntax en structuur

Basis JSON-datatypes

{
 "string_waarde": "tekst",
 "number_waarde": 42,
 "decimal_waarde": 3.14159,
 "boolean_waarde": true,
 "null_waarde": null,
 "array_waarde": [1, 2, 3, "vier"],
 "object_waarde": {
 "nested_key": "nested_value"
 }
}

Persoon-voorbeeld (vergelijkbaar met XML)

{
 "persoon": {
 "bsn": "123456789",
 "geslachtsnaam": {
 "voorvoegsel": "van der",
 "geslachtsnaamStam": "Berg"
 },
 "voornamen": "Jan Peter",
 "geboortedatum": "1985-03-15",
 "adres": {
 "straatnaam": "Hoofdstraat",
 "huisnummer": 42,
 "huisnummertoevoeging": "A",
 "postcode": "1234AB",
 "woonplaatsnaam": "Amsterdam"
 },
 "contactgegevens": [
 {
 "soort": "email",
 "waarde": "jan.vandenberg@example.com"
 },
 {
 "soort": "telefoon",
 "waarde": "06-12345678"
 }
 ]
 }
}

JSON vs XML-vergelijking

XML-versie:

4.3 SOAP-protocol

Wed, 04 Mar 2026 00:00:00 +0000

4.3 SOAP-protocol

Kent het SOAP-protocol voor webservices (structuur, WSDL, security, foutafhandeling).

Wat is SOAP?

SOAP (Simple Object Access Protocol, later hernoemd naar Service Oriented Architecture Protocol) is een messaging-protocol voor het uitwisselen van gestructureerde informatie in web services. SOAP is een W3C-standaard die zwaar wordt gebruikt in enterprise- en overheidsomgevingen voor betrouwbare, veilige communicatie tussen systemen.

Kerneigenschappen:

Protocol-agnostic: Werkt over HTTP, HTTPS, SMTP, TCP
Platform-independent: Kan tussen verschillende systemen communiceren
Extensible: Uitbreidbaar met headers en security-features
Standardized: Strikte W3C-specificatie met tooling-support

SOAP-berichtstructuur

Basis SOAP-envelope

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:tns="http://example.org/persoon-service">

 <!-- Optionele headers -->
 <soap:Header>
 <tns:Authentication>
 <tns:Username>gemeente_amsterdam</tns:Username>
 <tns:Token>abc123-xyz789</tns:Token>
 </tns:Authentication>
 </soap:Header>

 <!-- Verplichte body -->
 <soap:Body>
 <tns:GetPersoonRequest>
 <tns:BSN>123456789</tns:BSN>
 </tns:GetPersoonRequest>
 </soap:Body>
</soap:Envelope>

SOAP-response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
 xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:tns="http://example.org/persoon-service">

 <soap:Body>
 <tns:GetPersoonResponse>
 <tns:Persoon>
 <tns:BSN>123456789</tns:BSN>
 <tns:Voornaam>Jan</tns:Voornaam>
 <tns:Achternaam>Berg</tns:Achternaam>
 <tns:Geboortedatum>1985-03-15</tns:Geboortedatum>
 <tns:Adres>
 <tns:Straat>Hoofdstraat 42</tns:Straat>
 <tns:Postcode>1234AB</tns:Postcode>
 <tns:Plaats>Amsterdam</tns:Plaats>
 </tns:Adres>
 </tns:Persoon>
 </tns:GetPersoonResponse>
 </soap:Body>
</soap:Envelope>

SOAP Fault (foutafhandeling)

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <soap:Fault>
 <soap:Code>
 <soap:Value>soap:Client</soap:Value>
 <soap:Subcode>
 <soap:Value>tns:InvalidBSN</soap:Value>
 </soap:Subcode>
 </soap:Code>
 <soap:Reason>
 <soap:Text xml:lang="nl">
 BSN '12345678X' is geen geldig Burgerservicenummer
 </soap:Text>
 </soap:Reason>
 <soap:Detail>
 <tns:ValidationError>
 <tns:Field>BSN</tns:Field>
 <tns:Message>BSN moet uit precies 9 cijfers bestaan</tns:Message>
 <tns:Code>BSN_INVALID_FORMAT</tns:Code>
 </tns:ValidationError>
 </soap:Detail>
 </soap:Fault>
 </soap:Body>
</soap:Envelope>

WSDL (Web Service Description Language)

WSDL beschrijft de interface van een SOAP web service - welke operaties beschikbaar zijn, hoe berichten gestructureerd zijn, en hoe de service te bereiken is.

4.4 HTTP-protocol voor REST-API's

Wed, 04 Mar 2026 00:00:00 +0000

4.4 HTTP-protocol voor REST-API’s

Beheerst HTTP als protocol voor REST-API’s (methods, status codes, headers, caching).

HTTP-basics voor API’s

HTTP (Hypertext Transfer Protocol) vormt de basis van moderne web-API’s. In REST-architectuur wordt HTTP gebruikt zoals het bedoeld is: als een complete application-layer protocol voor resource-manipulatie.

HTTP Request-structuur

POST /api/personen HTTP/1.1
Host: api.gemeente.nl
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: Gemeente-App/2.1.0
Content-Length: 156

{
 "bsn": "123456789",
 "voornaam": "Jan",
 "achternaam": "Berg",
 "geboortedatum": "1985-03-15"
}

HTTP Response-structuur

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/personen/pers_abc123
ETag: "v1.2.3"
Cache-Control: private, max-age=3600
Content-Length: 234

{
 "id": "pers_abc123",
 "bsn": "123456789",
 "voornaam": "Jan",
 "achternaam": "Berg",
 "geboortedatum": "1985-03-15",
 "created_at": "2024-03-05T14:30:00Z",
 "updated_at": "2024-03-05T14:30:00Z",
 "_links": {
 "self": "/api/personen/pers_abc123",
 "adres": "/api/personen/pers_abc123/adres"
 }
}

HTTP Methods voor CRUD-operaties

GET - Resource opvragen

# Single resource
GET /api/personen/123456789 HTTP/1.1
Host: api.gemeente.nl
Accept: application/json

# Collection met filters
GET /api/personen?achternaam=Berg&geboortejaar=1985 HTTP/1.1
Host: api.gemeente.nl
Accept: application/json

# Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=300

{
 "data": [
 {
 "id": "pers_123",
 "voornaam": "Jan",
 "achternaam": "Berg"
 }
 ],
 "pagination": {
 "total": 1,
 "page": 1,
 "per_page": 25
 }
}

POST - Resource aanmaken

POST /api/personen HTTP/1.1
Host: api.gemeente.nl
Content-Type: application/json
Content-Length: 95

{
 "bsn": "987654321",
 "voornaam": "Maria",
 "achternaam": "Jansen"
}

# Success Response
HTTP/1.1 201 Created
Location: /api/personen/pers_xyz789
Content-Type: application/json

{
 "id": "pers_xyz789",
 "bsn": "987654321",
 "voornaam": "Maria",
 "achternaam": "Jansen",
 "created_at": "2024-03-05T14:30:00Z"
}

# Error Response
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
 "type": "https://api.gemeente.nl/problems/validation-error",
 "title": "Validation Failed",
 "status": 400,
 "detail": "Het verstrekte BSN is al in gebruik",
 "instance": "/api/personen",
 "invalid_params": [
 {
 "name": "bsn",
 "reason": "BSN moet uniek zijn"
 }
 ]
}

PUT - Resource volledig vervangen

PUT /api/personen/pers_123 HTTP/1.1
Host: api.gemeente.nl
Content-Type: application/json
If-Match: "v1.2.3"

{
 "bsn": "123456789",
 "voornaam": "Johannes",
 "achternaam": "van den Berg",
 "geboortedatum": "1985-03-15"
}

# Success Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "v1.2.4"

{
 "id": "pers_123",
 "bsn": "123456789",
 "voornaam": "Johannes",
 "achternaam": "van den Berg",
 "geboortedatum": "1985-03-15",
 "updated_at": "2024-03-05T14:35:00Z"
}

# Conflict Response (optimistic locking)
HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
 "type": "https://api.gemeente.nl/problems/stale-data",
 "title": "Resource Modified",
 "status": 412,
 "detail": "De resource is gewijzigd door een andere gebruiker"
}

PATCH - Gedeeltelijke resource-update

PATCH /api/personen/pers_123 HTTP/1.1
Host: api.gemeente.nl
Content-Type: application/json-patch+json
If-Match: "v1.2.4"

[
 {
 "op": "replace",
 "path": "/voornaam",
 "value": "Jan"
 },
 {
 "op": "add",
 "path": "/emailadres",
 "value": "jan.vandenberg@example.com"
 }
]

# Alternative: JSON Merge Patch
PATCH /api/personen/pers_123 HTTP/1.1
Content-Type: application/merge-patch+json

{
 "voornaam": "Jan",
 "emailadres": "jan.vandenberg@example.com"
}

DELETE - Resource verwijderen

DELETE /api/personen/pers_123 HTTP/1.1
Host: api.gemeente.nl
If-Match: "v1.2.4"

# Success Response (no content)
HTTP/1.1 204 No Content

# Success Response (with info)
HTTP/1.1 200 OK
Content-Type: application/json

{
 "message": "Persoon succesvol verwijderd",
 "deleted_at": "2024-03-05T14:40:00Z"
}

# Conflict Response
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
 "type": "https://api.gemeente.nl/problems/cannot-delete",
 "title": "Cannot Delete Resource",
 "detail": "Persoon kan niet worden verwijderd vanwege actieve zaken"
}

HTTP Status Codes

Success Codes (2xx)

200 OK # Successful GET, PUT, PATCH
201 Created # Successful POST (resource created)
202 Accepted # Request accepted (async processing)
204 No Content # Successful DELETE or PUT (no response body)
206 Partial Content # Partial GET (range requests)

Client Error Codes (4xx)

400 Bad Request # Malformed request
401 Unauthorized # Authentication required
403 Forbidden # Authorization failed
404 Not Found # Resource doesn't exist
405 Method Not Allowed # HTTP method not supported
406 Not Acceptable # Unsupported Accept header
409 Conflict # Resource conflict (e.g., duplicate)
410 Gone # Resource permanently deleted
412 Precondition Failed # If-Match, If-None-Match failed
413 Payload Too Large # Request body too large
415 Unsupported Media Type # Unsupported Content-Type
422 Unprocessable Entity # Semantic validation failed
429 Too Many Requests # Rate limiting

Server Error Codes (5xx)

500 Internal Server Error # Generic server error
501 Not Implemented # Feature not implemented
502 Bad Gateway # Upstream service error
503 Service Unavailable # Temporary service outage
504 Gateway Timeout # Upstream service timeout

HTTP Headers voor API’s

Request Headers

Authentication/Authorization:

4.5 Formaat- en protocolkeuzes

Wed, 04 Mar 2026 00:00:00 +0000

4.5 Formaat- en protocolkeuzes

Kan afgewogen keuzes maken tussen verschillende uitwisselingsformaten en protocollen op basis van context en requirements.

Decision Framework voor Format- en Protocolkeuze

Het kiezen van het juiste uitwisselingsformaat en protocol is een strategische beslissing die lange-termijn impact heeft op maintainability, performance en interoperabiliteit. Voor overheidsorganisaties zijn er specifieke overwegingen die deze keuze beïnvloeden.

Evaluatie-criteria

Technical Criteria:

Performance: Message-size, parsing-speed, bandwidth-usage
Complexity: Development-effort, debugging-ease, tooling
Interoperability: Cross-platform support, legacy-compatibility
Security: Built-in security features, vulnerability-resistance
Scalability: High-volume handling, caching-support

Business Criteria: