RESTful API Een RESTful API is een gebaseerd op de Representational state transfer (REST) is een softwarearchitectuur.

Transcriptie

1 NOTITIE Onderwerp : Uitleg van gebruikte termen bij gegevens- en berichtenstandaarden Van : VNG Realisatie Aan : Regiegroep Gegevens- en Berichtenstandaarden Datum : 29 mei 2018 Dit document legt een aantal relevante termen uit. Dit zijn de meest relevante termen die worden gebruikt in het kader van het vernieuwen van de standaarden. Deze notitie is opgesteld op verzoek van de Regiegroep Gegevens- en Berichtenstandaarden. API Wanneer we spreken over "API's", bedoelen we kleine, scherp gedefinieerde, voor een businessbehoefte doelmatige en voor consumers van de API/service eenvoudig te begrijpen en eenvoudig te implementeren webservices. VNG-Realisatie zet samen met gemeenten de komende tijd in op het ontwikkelen van standaarden in de vorm van REST-API s. Deze REST-API s worden gedefinieerd op basis van de functionele vraag vanuit gemeenten, zodat deze gemakkelijker te implementeren zijn en interpretatieverschillen ernstig worden teruggebracht. Uiteraard moeten ze passen in de architectuur van een (landelijk) gegevenslandschap. RESTful API Een RESTful API is een gebaseerd op de Representational state transfer (REST) is een softwarearchitectuur. Representational state transfer (REST) is een software architectuurstijl die bestaat uit een set afgestemde architecturele constraints die toegepast zijn op componenten, koppelingen en gegevens elementen, binnen een gedistribueerd hypermedia systeem. REST beschrijft 6 beperkingen (constraints) op de architectuur van gegevensuitwisseling: Uniform Interface Stateless Cacheable Client-Server Layered System Code on Demand (optional) Bronsysteem Een Bronsysteem is de plaats waar het gegeven voor het eerst wordt vastgelegd. Voor elk gegeven dat gebruit wordt voor de gemeentelijke taakuitoefening is er één bron. Er zijn bronnen voor landelijke basisgegevens en voor gemeentelijke kerngegeven. Bronsystemen kunnen buitengemeentelijk zijn zoals basisregistraties, of binnengemeentelijk. Voor gegevens die binnengemeentelijk worden vastgelegd, maar ook tussen gemeenten beschikbaar moeten zijn, VNG Realisatie Nassaulaan 12 Den Haag Postbus GK Den Haag realisatie@vng.nl IBAN: NL23BNGH KvK:

2 kunnen landelijke voorzieningen dienen als gedelegeerde bron voor de buitengemeentelijke gegevens. JSON JSON of JavaScript Object Notation, is een gestandaardiseerd gegevensformaat. JSON maakt gebruik van voor de mens leesbare tekst in de vorm van data-objecten die bestaan uit een of meer attributen met bijbehorende waarden. Het wordt hoofdzakelijk gebruikt voor uitwisseling van data tussen server en webapplicatie, als een alternatief voor xml. bron: Resource Onder Resources wordt in deze contect verstaan Web Resources. Een Web Resource wordt gebruikt om te verwijzen naar target van uniform resource identifier (URI). Met een URI wordt een gegeven geidentificeerd wat gebruikt kan worden in bijvoorbeeld gegevensuitwisseling. bron: Het fundamenteel concept in elke RESTful API is de resource. Een resource is een object met een type, bijbehorende data, relaties met andere resources en een aantal operaties om deze te bewerken. Resources worden aangeduid met zelfstandige naamwoorden (niet werkwoorden!) die relevant zijn vanuit het perspectief van de afnemer van de API. Dus resources zijn zelfstandige naamwoorden en operaties zijn werkwoorden. Operaties zijn acties die op resources worden uitgevoerd. bron: DSO architectuur API strategie Object Een ding, een tastbaar iets, in de werkelijkheid, zoals daarnaar gekeken wordt vanuit een bepaald domein. Het wordt veelal als niet politiek correct beschouwd mensen als objecten te zien. In dit kader, de informatievoorziening, beschouwen we evenwel natuurlijke en niet-natuurlijke personen wel als objecten. Tastbaar moet hierbij ruim geïnterpreteerd worden. Het gaat niet alleen om fysiek herkenbare objecten zoals auto s, gebouwen en mensen, ook om zogenaamde virtuele objecten waarover binnen het domein door betrokkenen gecommuniceerd wordt zoals kadastrale percelen, (maatschappelijke) activiteiten en processen. Hoe een tastbaar iets als een object beschouwd wordt, hangt af van het domein waarvoor dat tastbaar iets relevant is. Zo wordt de gebouwde omgeving in het ene domein beschouwd als een verzameling gebouwen terwijl een ander domein daarin panden onderscheidt. Een object is voor een domein relevant als eigenschappen (kenmerken) daarvan van belang zijn voor het functioneren van dat domein. bron: MIM (voorheen KKG): VNG Realisatie 2/5

3 Objecttype De typering van een groep objecten (in de werkelijkheid) die binnen een domein relevant zijn en als gelijksoortig worden beschouwd. Jan, Piet en Marie zijn mensen die vanuit het Burgerzaken-domein beschouwd worden als objecten van het type natuurlijk persoon. In een ander domein, de volksmond, noemen we dit mens wat ook een objecttype is. In weer een ander domein is Jan van het type vergunninghouder en Piet en Marie niet, omdat aan hen (nog) nooit een vergunning verleend is. Objecttypen zijn een abstractie van de werkelijkheid oftewel we beogen hiermee de werkelijkheid zo getrouw mogelijk te beschrijven, binnen de context van het domein. Dit staat geheel los van het vastleggen van gegevens over objecten van een type in een registratie. Daartoe is veelal een interpretatie nodig (van die werkelijkheid cq. die objecttypen) naar eenheden die in een registratie vastgelegd kunnen worden (records, entiteiten e.d.) op basis van andere overwegingen. Bron: MIM (voorheen KKG) Entiteittype Wanneer een objecttype wordt vertaald naar een structuur in een bericht, noemen we dit een entiteittype. Een entiteittype is dus vertaling van een objecttype naar de structuur waarin deze kan worden opgenomen in een bericht voor gegevensuitwisseling in een API of service. Semantisch Informatiemodel (SIM) Modellering van de werkelijkheid binnen het beschouwde domein, v.w.b. informatie daarvan, onafhankelijk van ontwerp van en implementatie in systemen. Het geeft een zo getrouw mogelijke beschrijving van die werkelijkheid en is in natuurlijke taal geformuleerd. Een dergelijk model definieert het wat : welke concepten ( dingen ) worden onderscheiden (in de beschouwde werkelijkheid), wat betekenen zij, hoe verhouden ze zich tot elkaar en welke informatie (eigenschappen) is daarvan relevant. Het dient als taal waarmee domeinexperts kunnen communiceren met informatie-analisten en verschaft een eenduidige interpretatie van die werkelijkheid ten behoeve van deze communicatie. Een conceptueel informatiemodel wordt dan ook opgesteld voor gebruik door mensen, zodat de business en de ICT-specialisten elkaar gaan begrijpen. Semantisch Informatiemodel is een synoniem van Conceptueel Informatiemodel zoals gedefinieerd in het Metamodel voor Informatiemodellering (MIM). bron: MIM (voorheen KKG) UitwisselingsGegevensModel (UGM) Beschrijft hoe de, in het conceptuele informatiemodel onderscheiden, concepten gebruikt worden bij de interactie tussen systemen en hun gebruikers en tussen systemen onderling. Anders gezegd, een model van de representatie van informatie over de werkelijkheid in digitale registraties en in de uitwisseling daartussen. Het gaat hierbij, in tegenstelling tot een conceptueel model, dus veel meer om het hoe. Het slaat de brug tussen werkelijkheid en systemen maar beschrijft nog niet de implementatie in die systemen. Een dergelijk model wordt in een formele taal beschreven en wordt VNG Realisatie 3/5

4 waar mogelijk gegenereerd vanuit het conceptueel model. Het logisch model wordt opgesteld voor ICT-interoperabiliteit, voor gebruik door met name de ontwerpers, bouwers en beheerders van ICTvoorzieningen. Uitwisselingsgegevensmodel is een synoniem van Logisch Informatiemodel zoals gedefinieerd in het Metamodel voor Informatiemodellering (MIM). bron: MIM (voorheen KKG) In een Uitwisselingsgegevensmodel (UGM) worden de gegevens en relaties zoals deze in een Semantisch Informatiemodel (SIM) zijn beschreven geoptimaliseerd voor gegevensuitwisseling. Qua enkelvoudige gegevens (elementen) vinden onder andere de volgende optimalisaties plaats: namen met spaties worden geconverteerd naar camelcase, formaten worden formeel gespecificeerd door middel van "patterns". Indien noodzakelijk kunnen qua samengestelde gegevens (entiteittypen) en relaties de volgende optimalisaties worden uitgevoerd: samenvoegen van entiteittypen, platslaan van relaties. Een Uitwisselingsgegevensmodel bestaat uit entiteittypen, eigenschappen (elementen) daarvan/daarin en relaties tussen entiteittypen. Het uitwisselingsgegevensmodel wordt gemodelleerd in UML. De structuren van entiteittypen zoals beschreven in het UGM vormen de basis voor de berichten zoals die beschreven staan in het Berichtstructuurmodel (BSM). BerichtStructuurModel (BSM) Een bericht in een koppelvlakstandaard wordt gemodelleerd in een Bericht Structuur Model (BSM). Het BSM is een UML klassediagram waarmee de structuur van een specifiek bericht wordt vastgelegd. Op basis van het BSM kunnen de technische specificaties van berichten (xsd's of open API specificatie) worden gegenereerd. In een BerichtStructuurModel worden berichten vormgegeven op basis van een UitwisselingsGegevensModel. Alle onderdelen uit een UGM kunnen worden hergebruitk in een BSM. In een BerichtStructuurmodel worden alleen die onderdelen van het UGM opgenomen die daadwerkelijk worden gebruikt in het bericht. Dat betekent dat er vaak gebruik zal worden gemaakt van een deel van de attributen van een entiteit en ook mogelijk een deel van de relaties wordt gebruikt. Ook de enumeratiewaarden van een Enumeratie kunnen bepekrt worden (niet veranderd). Een BSM beschrijft de berichtstructuren onafhankelijk van een eventueel te gebruiken formaat of uitwisselstandaard (StUF soap/xml of REST/JSON API). Voorbeelden zijn vraag- en antwoordbericht of een kennisgevingsbericht. Vanuit een BSM kan eenzelfde bericht in verschillende formaten gegenereerd worden. VNG Realisatie 4/5

5 Koppelvlakstandaard In een koppelvlak wordt zo specifiek en doelgericht mogelijk vastgelegd hoe een koppelvlak moet werken. Dit bevat ten minste de koppelvlakarchitectuur, berichtinteracties, functionele- en technische berichtdefinities (berichtschema s). In een koppelvlakstandaard worden modellen en afspraken uit de bovenliggende niveaus van standaardisatie gebruikt op basis van een specifieke businessbehoefte aan gegevensuitwisseling. Een koppelvlakstandaard wordt gebruikt voor het daadwerkelijk implementeren van services/api s. Gegevensuitwisseltechnieken We ontwikkelen, gebruiken en beheren standaarden die o.a. de technische aspecten van gegevensuitwisseling beschrijven. Deze standaarden worden koppelvlakoverstijgend beschreven en beheerd. De beschrijving van een gegevensuitwisseltechniek kan betrekking hebben op protocolbindingen (zoals http, soap) of op de opbouw en afhandeling van berichten voor verschillende interactiepatronen. Deze standaarden beschrijven niet de gegevens in berichten, maar beschrijven op welke manier gegevens in berichten worden opgenomen, hoe berichten eruit zien om een bepaald resultaat bij de ontvanger van het bericht te kunnen verwachten, hoe ontvangen berichten geïnterpreteerd moeten worden, hoe ontvangst en verwerking worden bevestigd, hoe fouten worden teruggemeld, naamgevingsconventies, enz. We onderscheiden op dit moment twee gescheiden technische onderlagen, hoewel we ons niet hiertoe zullen limiteren: StUF (SOAP/XML) (RESTful) API (http(s), JSON) VNG Realisatie 5/5