AGIV - KLIP Web API 0.6

INHOUDSTAFEL INHOUDSTAFEL... 2 1. INLEIDING... 3 A. SCOPE... 3 a. Scope van het project KLIP Digitale Fase... 3 b. Scope van dit document... 3 c. Belangrijke opmerking rond termen en taalgebruik... 4 B. OVERZICHT... 4 C. DOCUMENT REFERENTIE SYSTEEM... 4 a. Documenten van toepassing... 4 b. Externe referenties... 4 c. Technische woordenlijst... 5 2. INHOUDELIJKE TERMINOLOGIE EN VERTALINGEN... 5 3. DE DRIE ONDERDELEN VAN DE SPECIFICATIE... 7 A. INLEIDING... 7 B. COMMUNICATIE... 7 C. BEVEILIGING... 10 Copyright 2014 AGIV KLIP Web API Page 2 of 11

1. INLEIDING A. SCOPE a. Scope van het project KLIP Digitale Fase Het AGIV is het uitvoerend orgaan van het samenwerkingsverband GDI-Vlaanderen dat opgericht is binnen de Vlaamse Overheid om het optimaal gebruik van geografische informatie binnen onder andere de Vlaamse overheidsdiensten (niveau Vlaanderen, provincies, steden en gemeenten) te stimuleren en te coördineren. Het AGIV verzamelt bestaande geografische gegevensbronnen of maakt zelf geografische gegevensbronnen aan en zet deze om tot informatieproducten die binnen de verschillende overheidsdiensten en de partners gebruikt kunnen worden in de dagelijkse werking. Naast de geografische gegevensbronnen ontwikkelt het ook diensten voor toegepast gebruik en services, die de integratie van de geografische informatie in de dagelijkse werking ondersteunen (KLIP, CRAB web services, GIPOD ). In de beheersovereenkomst 2011-2015 die het AGIV afsloot met de Vlaamse regering werd onder strategische operationele doelstelling 6 Uitbouwen van oplossingen voor toegepast gebruik van geografische informatie het strategisch project 6.1 Informatiemodel kabels en leidingen (IMKL) opgenomen. Tegen 2015 zal het AGIV digitale planafhandeling op basis van het IMKL via het KLIP mogelijk maken. Het Kabel en Leiding Informatie Portaal (KLIP) heeft als hoofddoel graafschade aan kabels en leidingen te beperken. In een eerste fase door het ontsluiten van bestaande geo-informatie te optimaliseren en in een tweede fase door de uitwisseling van kabel- en leidinginformatie te bevorderen tussen de beheerders en gebruikers van kabel- en leidinginformatie. De eerste fase (www.klip.be) is sinds maart 2007 operationeel en het gebruik is verankerd in het KLIP-decreet 1. De tweede fase betreft het valideren van het informatiemodel voor kabelsen leidingen (IMKL) en het implementeren ervan in het KLIP door de digitale uitwisseling van kabel- en leidinginformatie mogelijk te maken. Het GRB zal hierbij als uniform referentiekader gebruikt worden voor de leidingregistratie. b. Scope van dit document De scope van dit document is een inleiding te geven tot de specificaties van de machine interfaces voor de planaanvraagmodule van het KLIP-platform. In een volgende versie zal het document uitgebreid worden met de IMKL-module. Het beschrijft de gebruikte terminologie en de opbouw van de specificaties. Verdere details en de specificaties zelf kunnen geraadpleegd worden op de volgende url: https://klipdftest.cloudapp.net/api/help (in afwachting van een definitieve url) De machine interfaces noemen we de KLIP Web API 1.0. Deze KLIP Web API 1.0 is een Web API [R1]. 1 Decreet van 14 maart 2008 houdende de ontsluiting en de uitwisseling van informatie over ondergrondse kabels en leidingen - (B.S.06.05.2008). Meer info: http://www.agiv.be/gis/organisatie/?catid=126 Copyright 2014 AGIV KLIP Web API Page 3 of 11

De externe partijen die met het KLIP kunnen communiceren zijn: Planaanvragers (PAV): Partijen die planaanvragen indienen via het KLIP; Kabel- en leidingbeheerders: Partijen die planaanvragen ontvangen via het KLIP en deze beantwoorden door op IMKL-conforme wijze plandata aan het KLIP te bezorgen. c. Belangrijke opmerking rond termen en taalgebruik De concepten en termen rond de informatie die wordt uitgewisseld via de KLIP Web API 1.0, de diverse deelcommunicaties en de beveiligingsaspecten worden in het Engels uitgedrukt. Voor alle Engelse termen is er een Nederlandse vertaling voorzien. B. OVERZICHT Het vervolg van dit document bevat de volgende hoofdstukken: Hoofdstuk 2: Belangrijkste inhoudelijke terminologie en vertalingen; Hoofdstuk 3: De drie onderdelen van de specificatie; C. DOCUMENT REFERENTIE SYSTEEM a. Documenten van toepassing A1 A2 A3 AGIV-IMKL2.1-DataModel AGIV-WebAPI AGIV-URI Strategie b. Externe referenties R1 1.1.1.1.1.1 Wikipedia omschrijving van een Web API, http://en.wikipedia.org/wiki/web_api Copyright 2014 AGIV KLIP Web API Page 4 of 11

c. Technische woordenlijst Term Definitie URI Uniform Resource Identifier URN Uniform Resource Name URL Uniform Resource Locator ORM Object Role Model UML Unified Modeling Language TAW Tweede Algemene Waterpassing PMKL Presentatie Model Kabels en Leidingen IMKL Informatie Model Kabels en Leidingen GML Geography Markup Language SVG Scalable Vector Graphics SLD Styled Layer Descriptor KLB Kabel en Leiding Beheerder INSPIRE US INSPIRE Utility Services 3.0rc3 GRB Grootschalig Referentie Bestand 2. INHOUDELIJKE TERMINOLOGIE EN VERTALINGEN De twee partijen die communiceren met het KLIP zijn de planaanvragers en de kabel- en leidingbeheerders, afgekort als PAV en KLB. De KLIP Web API 1.0 is opgesteld in het Engels en gebruikt dus Engelse termen voor alle concepten. Daarom wordt: PAV: MRI, dit is Map Request Initiator ; KLB: UNA, of Utility Network Authority. De belangrijkste term in deze versie van dit document is Planaanvraag, hetgeen vertaald wordt als MapRequest. Een MapRequest object wordt door een MRI naar het KLIP gestuurd. Het opvragen door een UNA van een MapRequest object resulteert in een UNAMapRequest object. Indien er iets misloopt tijdens het doorsturen of bevragen van objecten wordt door het KLIP een xerrorresponse 2 of xwarningresponse teruggeven, waarin de fouten worden opgesomd. Het verschil tussen een error en warning bestaat erin dat in geval van error de gestuurde boodschap niet geaccepteerd kan worden terwijl dit wel kan bij warnings. Een warning geeft een advies om een bepaald deel van de inhoud van de boodschap te verbeteren. 2 Waarbij de x vervangen wordt door de specifieke naam van het object in kwestie. Copyright 2014 AGIV KLIP Web API Page 5 of 11

Parameters planaanvraag Parameter ClientId DateReceived DeliveryAddressAdditionalLine DeliveryAddressBox DeliveryAddressCity DeliveryAddressCountryCode DeliveryAddressStreet DeliveryAddressStreetNumber DeliveryAddressZip DeliveryCompany DeliveryEmail DeliveryFax DeliveryFirstName DeliveryLastName DeliveryMobile DeliveryRole DeliveryTelephone DeliveryTitle EndDate ExcavationDepth ExcavationDescription ExcavationLocation ExcavationMethod ExcavationType MaprequestId MapRequestInitiatorCompany MapRequestInitiatorEmail MapRequestInitiatorFirstName MapRequestInitiatorLastName MapRequestInitiatorRole MapRequestInitiatorTelephone MapRequestInitiatorTitle MapRequestType MapRequestZone Reference StartDate Status Nederlandstalige omschrijving Lokale identificator van de planaanvraag (uniek binnen de organisatie van de planaanvrager) Ontvangstdatum van planaanvraag door KLIP Extra adresregel van plannenbestemmeling Bus plannenbestemmeling Woonplaats plannenbestemmeling Landcode (ISO) plannenbestemmeling (zie codelijst CountryCodes) Straatnaam plannenbestemmeling Huisnummer plannenbestemmeling Postcode plannenbestemmeling Organisatie plannenbestemmeling E-mailadres plannenbestemmeling Faxnummer plannenbestemmeling Voornaam plannenbestemmeling Achternaam plannenbestemmeling GSM-nummer plannenbestemmeling Rol van de plannenbestemmeling (zie codelijst MapRequestRoles) Telefoonnummer plannenbestemmeling Aanspreektitel plannenbestemmeling Einddatum van de werken Graafdiepte van de werken Omschrijving van de werken Locatie van de werken Aard van de werken (zie codelijst ExcavationMethods) Type van de werken (zie codelijst ExcavationTypes) De unieke KLIP Identificator van een planaanvraag Organisatie van de planaanvrager E-mailadres van de planaanvrager Voornaam van de planaanvrager Achternaam van de planaanvrager Rol van de planaanvrager (zie codelijst MapRequestRoles) Telefoonnummer van de planaanvrager Aanspreektitel van de planaanvrager Type planaanvraag (zie codelijst MaprequestType) Geometrie van de planaanvraag (polygoon) Referentie van de planaanvraag (of groep van planaanvragen) Startdatum van de werken Status van de planaanvraag (zie codelijst MapRequestStatuses) Copyright 2014 AGIV KLIP Web API Page 6 of 11

Parameters KLB Parameter DisplayName UnaZones Nederlandstalige omschrijving De weergegeven naam (of displaynaam) van een KLB / de aanduiding van een KLB Een lijst van alle KLB-zones van een KLB Parameters KLB Zone Parameter AlarmCentralTelephone ContactEmail ContactName ContactTelephone ExtraInformation IsArchived LastModified MapRequestEmail MapRequestResponder Name Nederlandstalige omschrijving Noodnummer van de betreffende KLB-zone E-mailadres dat een planaanvrager kan gebruiken om contact op te nemen met de betreffende KLB Naam van de contactpersoon Telefoonnummer dat een planaanvrager kan gebruiken om contact op te nemen met de betreffende KLB Extra informatie bestemd voor de planaanvrager ivm een KLB-zone Boolean die aanduidt of een KLB-zone nog in gebruik is. Datum van de laatste wijziging aan de KLB-zone Het e-mailadres van de KLB waar AGIV de planaanvragen naartoe zal sturen. Dit is een KLB-zone betrokken bij een planaanvraag Dit is de naam van een KLB-zone 3. DE DRIE ONDERDELEN VAN DE SPECIFICATIE A. INLEIDING De specificatie bevat drie onderdelen: de communicaties tussen externe partijen en het KLIP, de berichten die worden uitgewisseld tijdens die communicaties en het mechanisme dat gebruikt wordt om de uitwisseling te beveiligen. De Web API specificatie voor de KLIP Web API 1.0 is gebaseerd op REST. De reden voor deze keuze is dat deze webservice stijl eenvoudig, efficiënt, zeer breed ondersteund en compatibel is met verschillende platformen. Er wordt gekozen voor beveiliging met OAuth2.0 omdat deze een de facto en de juro standaard is voor beveiliging van REST Web API s. De AGIV OAuth2.0 beveiligingsservice is een dienst die door AGIV wordt aangeboden voor al haar toekomstige Web API s die beveiliging vereisen. Deze service is zelf ook een Web API. B. COMMUNICATIE Alle mogelijke communicaties tussen externe partijen en het KLIP gebeuren onafhankelijk van elkaar (via onderstaande methodes) en dienen in een welbepaalde volgorde uitgevoerd te worden (volgens het planaanvraagproces). Copyright 2014 AGIV KLIP Web API Page 7 of 11

Meer details ivm onderstaande methodes staan op de KLIP Web API helppagina, op volgende URL: https://klipdftest.cloudapp.net/api/help (in afwachting van een definitieve url). Momenteel onderscheiden we voor dit planaanvraagproces de volgende communicaties: Methodes voor de planaanvrager: MapRequestResponder/{id} (GET): Haal de informatie van een KLB-zone op. MapRequestResponders/{id} (GET): Haal de lijst op van KLB-zones die betrokken zijn bij een planaanvraag op. MriMapRequest/{id} (GET): Haal een planaanvraag op. MriMapRequest (POST): Dien een planaanvraag in. MriMapRequestQuery?<query> (GET): Zoek naar planaanvragen. Methodes voor de kabel- en leidingbeheerder: Una (GET): Haal de informatie over uw KLB op. UnaMapRequest/{id} (GET): Haal een planaanvraag op. UnaMapRequestConfirmation (POST): Bevestig een planaanvraag. UnaMapRequestQuery (GET): Zoek naar planaanvragen. UnaZone/{id} (GET): Haal informatie over een KLB-zone op. UnaZonesInvolved/{id} (GET): Haal een lijst op van bij een planaanvraag betrokken KLB-zones (enkel de zones van de eigen KLB worden weergegeven). Methodes voor het ophalen van codelijsten (of het detail van een code): CountryCode/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaalde landcode. CountryCodes (GET): Haal de codelijst van de landen en hun corresponderende Nederlandstalige omschrijving op. ExcavationMethod/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaalde code voor aard van werken. ExcavationMethods (GET): Haal de codelijst van aard van werken en corresponderende Nederlandstalige omschrijving op. ExcavationType/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaalde code voor type werken. ExcavationTypes (GET): Haal de codelijst van type werken en corresponderende Nederlandstalige omschrijving op. GeometryFormat/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaald geometrieformaat. GeometryFormats (GET): Haal de codelijst van geometrieformaten en corresponderende Nederlandstalige omschrijving op. MapRequestRole/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaalde rol van een planaanvrager. MapRequestRoles (GET): Haal de codelijst van alle rollen van een planaanvrager en corresponderende Nederlandstalige omschrijving op. MapRequestStatus/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaalde status van een planaanvraag. Copyright 2014 AGIV KLIP Web API Page 8 of 11

MapRequestStatuses (GET): Haal de codelijst van de planaanvraagstatussen en corresponderende Nederlandstalige omschrijving op. MapRequestType/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaald type van een planaanvraag. MapRequestTypes (GET): Haal de codelijst van de planaanvraagtypes en corresponderende Nederlandstalige omschrijving op. UnaStatus/{id} (GET): Haal de Nederlandstalige omschrijving op van een bepaalde status van een KLB betrokken bij een planaanvraag. UnaStatuses (GET): Haal de codelijst van de statussen van KLB s betrokken bij een planaanvraag en corresponderende Nederlandstalige omschrijving op. Methodes voor het ophalen van foutboodschappen (of het detail van een foutboodschap): GeneralError (GET): Algemene foutboodschappen MapRequestError (GET): Foutboodschappen die betrekking hebben op een planaanvraag. UnaError (GET): Foutboodschappen die betrekking hebben op een KLB. UnaZoneError (GET): Foutboodschappen die betrekking hebben op een KLBzone. Een opsomming van de verschillende soorten foutboodschappen met hun mogelijke waarden, kan geraadpleegd worden op de helppagina. (https://klipdftest.cloudapp.net/api/help/) Al deze communicaties worden geïnitieerd door een planaanvrager (MRI) of kabel- en leidingbeheerder (UNA) en zijn synchroon, d.w.z. dat binnen de sessie van een communicatie een antwoord wordt teruggestuurd door het KLIP. De verwerking van de POST en PUT wordt asynchroon gedaan. De communicaties maken gebruik van het standaard HTTPS protocol waarbij de POST en GET methodes gebruikt worden om respectievelijk objecten naar het KLIP te sturen en bij het KLIP op te halen. Deze moeten naar een KLIP URL worden gestuurd volgens onderstaand principe: Base URL: https://<domain>/ws/klip/v1 - voor codelijsten en foutboodschappen: https://<domain>/cl/klip/v1 - met service methode: https://<domain>/ws/klip/v1/mrimaprequest - met service en id: https://<domain>/ws/klip/v&/mrimaprequest/bc33706d-c184-4eaf- AE83- F9A065A79386 Copyright 2014 AGIV KLIP Web API Page 9 of 11

- met codelijst: https://<domain>/cl/klip/v1/maprequestroles - met code: https://<domain>/cl/klip/v1/maprequestrole/buildingowner De communicatie kan aan de hand van één van volgende uitwisselingsformaten gebeuren - JSON (geometrie in GeoJSON) - XML (geometrie in GML) C. BEVEILIGING De OAuth2.0 beveiligingsservice van AGIV heeft een eigen webpagina waar deze is gedocumenteerd. Zie: https://oauth.beta.agiv.be/authorization/help/ Het deel dat relevant is in de context van het KLIP is te vinden onder Calling a secured AGIV API from web server applications. In een latere versie zal deze documentatie ook in het Nederlands beschikbaar zijn. Copyright 2014 AGIV KLIP Web API Page 10 of 11