Messageservice 3.1 REST

Versie: Messageservice v3.1 REST

1 Inleiding

Deze handleiding bevat de algemene spelregels voor bedrijven uit de bouw- en installatiesector die gestandaardiseerde en elektronische berichten willen uitwisselen. Het is een sectorspecifiek basisdocument per om afspraken rond een REST API gebruik.

1.1 De REST Messageservice binnen de DICO Standaard

De DICO Standaard bestaat uit verschillende deelgebieden waar de berichten gebruikt kunnen worden. De Databerichtenset zijn weergegeven in de blauwe rij. De DICO Standaard kent ook de Onderhoudsberichten (oranje) en de Transactieberichtenset (groen) die respectievelijk de uitwisseling van product-/artikeldata en het order-to-pay proces beschrijven. In het rood vindt u de Verhuurberichten en onderaan vindt u de documentatie voor de MessageService.

Figuur 1 – Huidige berichten in de DICO Standaard

1.2 Wat is het doel van dit document?

In dit document leest u welke overkoepelende afspraken zijn gemaakt binnen de branche over het gebruik van de DICO REST API. De documentatie is met zorg samengesteld, mochten er onverhoopt toch fouten of onduidelijkheden in staan wordt u verzocht contact op te nemen met Ketenstandaard voor uitsluitsel. Gelieve niet zelf een interpretatie te maken, om zo dialecten van de standaard te voorkomen. Overige (technische) informatie is gepubliceerd op Semantic-Treehouse. De documentatie beschrijft het toepassingsgebied, proces en technische uitgangspunten van de DICO Standaard. De structuur, inhoud en gebruikersregels worden verder toegelicht op Swagger. Uiteindelijke DICO XML berichten en REST API moeten voldoen aan de beschreven eisen. Voor de daadwerkelijke uitwisseling van DICO berichten is een licentie vereist. Voor meer informatie en gebruikersvoorwaarden hierover, zie www.ketenstandaard.nl.

1.3 Samenstellers

Dit document wordt onderhouden door Ketenstandaard Bouw en Techniek. Ketenstandaard Bouw en Techniek beheert de DICO Standaard en faciliteert DICO Commissies voor de Bouw en Installatie sector. Bedrijven uit de sector zijn vertegenwoordigd binnen deze commissies, waarmee aansluiting op de informatiebehoefte van de sector gewaarborgd blijft. Voor vragen of opmerkingen over dit document kunt u contact opnemen met info@ketenstandaard.nl. 

2 DICO REST API

De DICO REST API is een uitwerking van de principes en afspraken die gelden rond het opzetten van een DICO REST API. Hierin is een onderscheid gemaakt tussen het opzetten van de verbinding (dit document) en de functies die uitgevoerd kunnen. De keuze hiervoor is gemaakt op verzoek van deelnemers van de DICO Standaard met als motivatie dat REST moderner is, eenvoudiger te implementeren, flexibeler en dat Microsoft SOAP wil uit faseren binnen hun .NET platform.

2.1 Conceptuele uitwerking

2.1.1 Toepassing
De DICO REST API richt zich op server to server (s2s) communicatie. Hierbij wordt uitgegaan van een “always online” principe wat betekend dat de partijen die van de DICO REST API gebruik maken altijd bereikbaar moeten zijn (binnen de gebruikelijke uptime principes van ICT). De berichten worden direct afgeleverd, bij aflevering volgt een standaard response code, al dan niet met een opvolgend bericht, naar aanleiding van het verstuurde bericht.

Figuur 2 - Schema server naar server communicatie

2.1.2 Rolverdeling
De DICO REST API beschrijft het opzetten van de verbinding en welke afspraken daar rondom zijn vastgelegd. Er wordt binnen de DICO REST API gepraat over de initiator en de ontvanger van de verbinding.  

3 Gebruik DICO REST API

3.1 Verbinding

Webbeveiliging is een voortdurend bewegend doelwit. Dit betekent lezen en op de hoogte blijven van wat er gebeurt als het gaat om webbeveiliging. Ketenstandaard adviseert om minimaal de verbinding op basis van HTTPS op te zetten en eventuele andere/hogere beveilingsnormen af te stemmen tussen de partijen onderling. De website van SSL.com is een mogelijke bron om op de hoogte te blijven van SSL/TLS en informatiebeveiliging. (Best practices: https://www.ssl.com/guide/ssl-best-practices/) Zoals eerder aangegeven dient deze informatie aangevuld te worden met eigen kennis en de laatste ontwikkelingen.

3.2 Authenticatie

Voor authenticatie is OAuth de gekozen methode. De configuratie OAuth valt buiten scope van de REST API. Wel worden de wijzen van authenticatie en autorisatie besproken. Hierbij is sprake van het verstrekken van tokens waarbij een geldigheidsduur van 1 uur wordt afgesproken voor de API. Authentiseren binnen OAuth gebeurt doormiddel van ClientID en ClientSecret. ClientID wordt volgens OAuth principes verstrekt door de ontvanger van de verbinding. Het ClientSecret wordt voor iedere implementatie uniek uitgegeven. Dat betekent dus niet voor ieder softwarepakket als geheel. Dit is omdat het de eerste stap is om te kijken of de tegenpartij gerechtigd is om de verbinding op te zetten.

3.3 Autorisatie

Autorisatie wordt in dit geval gezien als: “mag deze partij bij mij dit bericht afleveren en/of opvragen?”. Hierbij zit een deel van de functionaliteit binnen de berichten; namelijk identificatie via het GLN-nummer. Het is ook mogelijk om het GLN nummer via x-RelationId in de query mee te geven om kenbaar te maken van wie het bericht afkomstig is. Deze is terug te vinden in de specifieke actie in de betreffende publicatie.

3.4 Payload

De payload van de REST MessageService is in principe vrij, dat wil zeggen dat men alles in de payload kan versturen. Binnen de DICO Standaard definiëren we een aantal identifiers (X-MessageType, X-MessageFormat en X-MessageVersion) voor de DICO berichten die binnen de REST MessageService gebruikt kunnen worden. Deze identifiers zijn te vinden in de YAML file die bij de betreffende calls horen en kunnen in de loop van tijd worden aangevuld. Hierover wordt ook gecommuniceerd via de gebruikelijke kanalen. Deze worden per actie gedefinieerd en dienen exact uit de specificatie te worden overgenomen.

3.5 Foutafhandeling

Foutafhandeling gaat via de http-foutcodes. De REST API definieert wel de terug te geven codes bij een succesvolle afhandeling. Zie daarvoor de specifieke acties.