API-specificaties Melding doen

Over deze documentatie

In deze documentatie vindt u de API-specificaties waar uw applicatie moet aan voldoen om gebruikers van de gemeente app/Mijn Burgerprofiel app meldingen te laten doen. Zo kunt u met een beperkte configuratie meldingen beschikbaar maken in de gemeente app/Mijn Burgerprofiel app.

URL's en versiebeheer

De URL voor uw endpoint kan er als volgt uitzien:
https://<hostname>/v1/melding/configuration

Voeg altijd een versienummer toe aan de URL, in de vorm van een cijfer, bijv. v1, v2, …

Er kunnen nooit breaking changes bestaan binnen een bepaalde versie. Zijn er toch breaking changes nodig, zorg dan voor een nieuwe versie.

Foutberichten

De foutberichten die teruggeven worden moeten conform de API-design richtlijnen zijn. Deze zijn gebaseerd op RFC 7807 - Problem Details for HTTP API's.

Authenticatie

Het Vlaams Toegangsbeheer (ACM) wordt gebruikt als identity provider (IdP).

De authenticatie loopt via https://authenticatie.vlaanderen.be/docs/beveiligen-van-api/oauth-rest/ waarbij Mijn Burgerprofiel de afnemer (= Client) is en de dienstenleverancier als aanbieder (= Resource) optreedt.

Mijn Burgerprofiel zal bij het aanvragen van een access token de scope dv_mbp_incidents specificeren. Deze scope moet door de dienstenleverancier als default worden toegewezen aan de client. Dit kan eenvoudig via het beheersportaal van ACM.

Meer informatie: https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Authorization

Configuratie

Mijn Burgerprofiel haalt de configuratie op bij alle lokale besturen die zijn aangesloten bij een dienstenleverancier die een meldingen-applicatie aanbiedt. De dienstenleverancier bepaalt zelf voor welke lokale besturen een configuratie wordt teruggegeven.

Een configuratie bestaat uit:

De categorieën waarvoor een melding kan gedaan worden
Een JSON-schema
Specificaties waaraan de bijlage (attachment bij de melding) moet voldoen

Categorieën

Een melding kan worden gedaan voor meerdere categorieën. Een categorie bestaat uit:

id: unique identifier, vaak een UUID
name : betekenisvolle omschrijving van de categorie, bijv. wateroverlast, gebrek aan de weg, parkeerplaats, ….
parentId (optioneel): via de parentId worden hiërarchische niveau’s meegegeven aan de categorieën

Mijn Burgerprofiel ondersteunt maximaal 3 niveau’s en verwacht minimaal 1 categorie.

JSON-schema

Het JSON-schema definieert de verplichte velden. Bekijk een voorbeeld van een JSON-schema.

Mijn Burgerprofiel houdt alleen rekening met de ‘required’ (verplichte) specificaties en negeert de overige specificaties in het schema.

Mijn Burgerprofiel bepaalt aan de hand van het JSON-schema welke van onderstaande velden verplicht zijn:

description: omschrijving van de melding
location: adres of coördinaten
contactType: geeft aan op welke manier de melder zijn contact gegevens kan achterlaten (anoniem, authenticated, userInput)
contactattributen: firstname, lastname, rrn
adresattributen: street, number, box, zipcode, city
e-mail
phone

Bijlage

Het is mogelijk om de specificaties waaraan de bijlage (attachment bij de melding) moet voldoen te specificeren in de configuratie:

fileType: ondersteunde mediatypes in rfc6838-formaat
maxFileSize: maximale bestandsgrootte van één bijlage in KB
maxNumberOfFiles: het maximaal aantal bijlagen

Proces

Swagger-documentatie “Incidents” (Meldingen)

Voorbeeld JSON schema

JSON-Voorbeeld

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "required": [ "contactType", "contact" ],
  "properties": {
    "contactType": {
      "oneOf": [
        { "const": "authenticated" },
        { "const": "userInput" }
      ]
    },
    "contact": { "$ref": "#/definitions/Contact" },
    "location": { "$ref": "#/definitions/Location" }
  },
  "definitions": {
    "Contact": {
      "type": "object",
      "required": [ "firstname", "lastname" ],
      "properties": {
        "firstname": { "type": "string" },
        "lastname": { "type": "string" },
        "rrn": { "type": "number" },
        "address": { "$ref": "#/definitions/Address" },
        "email": { "type": "string" },
        "phone": { "type": "string" }
      }
    },
    "Address": {
      "type": "object",
      "required": [ "street", "number", "city" ],
      "properties": {
        "street": { "type": "string" },
        "number": { "type": "string" },
        "box": { "type": "string" },
        "zipcode": { "type": "string" },
        "city": { "type": "string" }
      }
    },
    "Location": {
      "type": "object",
      "properties": {
        "address": { "$ref": "#/definitions/Address" },
        "coordinates": { "$ref": "#/definitions/Coordinates" }
      }
    },
    "Coordinates": {
      "type": "object",
      "properties": {
        "long": {
          "type": "number",
          "format": "double"
        },
        "lat": {
          "type": "number",
          "format": "double"
        },
        "accuracy": {
          "type": "number",
          "format": "double"
        }
      }
    }
  }
}

Voorbeeld Response Configuraties

JSON-voorbeeld

{
  "configurations": [
    {
      "nisCode": 71022,
      "jsonSchema": {ZIE VOORBEELD JSON SCHEMA},
      "categories": [
        {
          "id": "c69e981e-db0d-4e96-8e8d-1049d350f48e",
          "name": "Groen, natuur en dieren"
        },
        {
          "id": "f0bd611a-68a1-4e68-ad06-9000556a1d81",
          "name": "Afval en reiniging"
        },
        {
          "id": "3ddd7a61-c620-421d-9724-22070e670224",
          "name": "Schade, defect"
        },
        {
          "id": "7a005ef2-0c56-4be4-8a70-caed94831799",
          "name": "Verkeer, parkeren"
        },
        {
          "id": "0443dd74-37ec-4f6c-ba83-3efdb7706a0c",
          "name": "Parkeren",
          "parentId": "7a005ef2-0c56-4be4-8a70-caed94831799"
        },
        {
          "id": "4b6de2f6-3cfe-4ccc-870b-5b1a4eb64763",
          "name": "Verkeersveiligheid",
          "parentId": "7a005ef2-0c56-4be4-8a70-caed94831799"
        },
        {
          "id": "1999b1a9-464c-429b-8833-7e1db49ddc9c",
          "name": "Wegenwerken",
          "parentId": "7a005ef2-0c56-4be4-8a70-caed94831799"
        },
        {
          "id": "6ea49d53-bdcf-4afa-9628-6a8a446be684",
          "name": "Mindervalide parkeerplaats",
          "parentId": "0443dd74-37ec-4f6c-ba83-3efdb7706a0c"
        },
        {
          "id": "8bdff1d8-fba0-4f04-b3d7-5f16eec8e079",
          "name": "Parkeerboete",
          "parentId": "0443dd74-37ec-4f6c-ba83-3efdb7706a0c"
        },
        {
          "id": "0b5789ab-78ef-4c0d-ac5d-ba993b27b380",
          "name": "Groenonderhoud",
          "parentId": "c69e981e-db0d-4e96-8e8d-1049d350f48e"
        },
        {
          "id": "2dc7da40-54ef-48a4-b265-41a5eb24f656",
          "name": "Dierenoverlast",
          "parentId": "c69e981e-db0d-4e96-8e8d-1049d350f48e"
        }
      ],
      "attachment": {
        "fileType": "image/*",
        "maxFileSize": 3000,
        "maxNumberOfFiles": 3
      }
    },
    {
      "nisCode": 12025,
      "jsonSchema": {},
      "categories": [
        {
          "id": "7c91800f-5e96-4876-9565-87c0f4831096",
          "name": "voorbeeld categorie 1"
        },
        {
          "id": "852f28ff-446f-4277-814d-f198e3bc5240",
          "name": "voorbeeld categorie 2 "
        }
      ],
      "attachment": {
        "fileType": [
          "image/*, application/pdf, application/msword"
        ],
        "maxFileSize": 500,
        "maxNumberOfFiles": 5
      }
    }
  ]
}

Voorbeeld Request Meldingen