AGIV - KLIP Web API 0.6

AGIV - KLIP Digitale Fase

Deliverable : AGIV-KLIPWebAPI0.5 Datum : 10/12/2013 Versie : 0.6 0.6


AGIV - KLIP Web API 0.6

© Copyright 2014 AGIV

KLIP Web API 0.6

Page 1 of 11



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


KLIP Web API 0.6

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-decreet1. 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


KLIP Web API 0.6

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

AGIV-IMKL2.1-DataModel

A2

AGIV-WebAPI

A3

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

KLIP Web API 0.6

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 xErrorResponse2 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.


KLIP Web API 0.6

Page 5 of 11



Parameters planaanvraag Parameter

Nederlandstalige omschrijving

ClientId

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)

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


KLIP Web API 0.6

Page 6 of 11



Parameters KLB Parameter


DisplayName

De weergegeven naam (of displaynaam) van een KLB / de aanduiding van een KLB Een lijst van alle KLB-zones van een KLB

UnaZones

Parameters KLB Zone Parameter


AlarmCentralTelephone ContactEmail

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

ContactName ContactTelephone

ExtraInformation IsArchived LastModified MapRequestEmail MapRequestResponder Name

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).


KLIP Web API 0.6

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? (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.


KLIP Web API 0.6

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- AE83F9A065A79386


KLIP Web API 0.6

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.


KLIP Web API 0.6

Page 10 of 11



END OF DOCUMENT


KLIP Web API 0.6

Page 11 of 11

AGIV - KLIP Web API 0.6

Recommend Documents