{
  "openapi": "3.0.3",
  "info": {
    "title": "VRNHN API",
    "description": "Openbare API van Veiligheidsregio Noord-Holland Noord.",
    "version": "2.1.0"
  },
  "servers": [
    {
      "url": "https://www.vrnhn.nl/api"
    }
  ],
  "tags": [
    {
      "name": "Incidenten",
      "description": "Incidenten en bijbehorende updates."
    },
    {
      "name": "Noodberichten",
      "description": "Gepubliceerde noodberichten."
    }
  ],
  "paths": {
    "/incidenten": {
      "get": {
        "tags": [
          "Incidenten"
        ],
        "summary": "Incidenten in de regio ophalen",
        "description": "De incidenten zijn gesorteerd op datum, nieuwste eerst.",
        "operationId": "getIncidents",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Filter incidenten op incidentdatum vanaf deze datum (YYYY-MM-DD)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "till",
            "in": "query",
            "description": "Filter incidenten op incidentdatum tot en met deze datum (YYYY-MM-DD)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Zoek in de titel en introtekst.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Aantal resultaten per pagina (1–50).",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incidenten met filters en paginering.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/incident"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/pagination"
                    },
                    "filters": {
                      "$ref": "#/components/schemas/incident-filters"
                    }
                  },
                  "required": [
                    "results",
                    "pagination",
                    "filters"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Ongeldige filter- of pagineringsparameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/api-error"
                }
              }
            }
          }
        }
      }
    },
    "/incidenten/{incidentId}": {
      "get": {
        "tags": [
          "Incidenten"
        ],
        "summary": "Incident ophalen",
        "operationId": "getIncident",
        "parameters": [
          {
            "name": "incidentId",
            "in": "path",
            "description": "Het numerieke ID van het incident.",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Het incident met bijbehorende updates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/incident"
                }
              }
            }
          },
          "404": {
            "description": "Incident niet gevonden.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/noodberichten": {
      "get": {
        "tags": [
          "Noodberichten"
        ],
        "summary": "Noodberichten ophalen",
        "operationId": "getEmergencyMessages",
        "parameters": [
          {
            "name": "example",
            "in": "query",
            "description": "Geef 1 op om een hardgecodeerd voorbeeldnoodbericht terug te krijgen. Dit is bedoeld om de API-uitvoer te testen wanneer er geen gepubliceerd noodbericht beschikbaar is.",
            "required": false,
            "schema": {
              "type": "integer",
              "enum": [1]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "De gepubliceerde noodberichten.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/noodbericht"
                      }
                    }
                  },
                  "required": [
                    "results"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "api-error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "incident": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "De titel van het incident"
          },
          "intro": {
            "type": "string",
            "description": "De introtekst van het incident"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "De datum van het incident"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Publieke webpagina van het incident en de updates."
          },
          "data_url": {
            "type": "string",
            "format": "uri",
            "description": "API-resource van het incident."
          },
          "theme_url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute URL naar de bijbehorende 'Wat kan ik doen bij'-themapagina",
            "nullable": true
          },
          "updates": {
            "type": "array",
            "description": "De updates bij dit incident, nieuwste eerst",
            "items": {
              "$ref": "#/components/schemas/incident-update"
            }
          }
        },
        "required": [
          "title",
          "intro",
          "date",
          "url",
          "data_url",
          "theme_url",
          "updates"
        ]
      },
      "incident-update": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "De titel van de update"
          },
          "text": {
            "type": "string",
            "description": "De tekst van de update"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "De publicatiedatum van de update"
          },
          "images": {
            "type": "array",
            "description": "De afbeeldingen bij de update",
            "items": {
              "$ref": "#/components/schemas/image"
            }
          }
        },
        "required": [
          "title",
          "text",
          "date",
          "images"
        ]
      },
      "noodbericht": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "De titel van het noodbericht"
          },
          "body": {
            "type": "string",
            "description": "HTML-inhoud van het noodbericht."
          },
          "read_more": {
            "type": "object",
            "nullable": true,
            "description": "Optionele link naar aanvullende informatie.",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "title": {
                "type": "string"
              }
            },
            "required": [
              "url",
              "title"
            ]
          },
          "screen_reader_indication": {
            "type": "string",
            "description": "Voorleeshulp-prefix voor screenreaders (bijv. 'Belangrijke mededeling')"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time",
            "description": "Laatst-bijgewerkt-tijdstip (ISO-8601). Alleen aanwezig als de weergave van de wijzigingsdatum is ingeschakeld."
          }
        },
        "required": [
          "title",
          "body",
          "read_more",
          "screen_reader_indication"
        ]
      },
      "image": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "De URL naar de afbeelding"
          },
          "thumbnail_url": {
            "type": "string",
            "format": "uri",
            "description": "De URL naar de thumbnail van de afbeelding",
            "nullable": true
          },
          "alt": {
            "type": "string",
            "description": "De alternatieve tekst voor de afbeelding",
            "nullable": true
          },
          "caption": {
            "type": "string",
            "description": "Het onderschrift van de afbeelding",
            "nullable": true
          }
        },
        "required": [
          "url",
          "thumbnail_url",
          "alt",
          "caption"
        ]
      },
      "pagination": {
        "type": "object",
        "description": "De toegepaste paginering",
        "properties": {
          "page": {
            "type": "integer",
            "description": "De huidige pagina",
            "minimum": 1
          },
          "resultsPerPage": {
            "type": "integer",
            "description": "Het aantal resultaten per pagina",
            "minimum": 1,
            "maximum": 50
          },
          "totalPages": {
            "type": "integer",
            "description": "Het totaal aantal pagina's",
            "minimum": 0
          },
          "totalResults": {
            "type": "integer",
            "description": "Het totaal aantal resultaten",
            "minimum": 0
          }
        },
        "required": [
          "page",
          "resultsPerPage",
          "totalPages",
          "totalResults"
        ]
      },
      "incident-filters": {
        "type": "object",
        "properties": {
          "since": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Begindatumfilter (YYYY-MM-DD)."
          },
          "till": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Einddatumfilter (YYYY-MM-DD)."
          },
          "search": {
            "type": "string",
            "nullable": true
        }
        },
        "required": [
          "since",
          "till",
          "search"
        ]
      }
    }
  }
}
