Het voorstel is om losse gegevens toe te staan in vrije StUF-berichten op voorwaarde dat er een vertaling is gedefinieerd naar een regulier vrij bericht (in het koppelvlak). Een voorbeeld in de context van het koppelvlak RSGB Bevragingen (rbs0310):
SOAP-versie:
<rbs:zoekNPSOpGeslachtsnaamGeboortedatum xmlns:rbs="http://www.stufstandaarden.nl/koppelvlak/rbs0310" ...>
<peiltijdstipMaterieel>2016-06-08</peiltijdstipMaterieel>
<geslachtsnaam>Jansen</geslachtsnaam>
<geboortedatum>1973-08-15</geboortedatum>
</rbs:zoekNPSOpGeslachtsnaamGeboortedatum>
REST-versie:
GET /gegevensmagazijn/NPS?peiltijdstipMaterieel=2016-06-08&geslachtsnaam=Jansen&geboortedatum=1973-08-15
Host: kinggemeenten.nl
De vertaling naar het reguliere vrije bericht is als volgt:
<rbs:zoekNPSOpGeslachtsnaamGeboortedatum xmlns:rbs="http://www.stufstandaarden.nl/koppelvlak/rbs0310" ...>
<rbs:selectie stuf:functie="selectie">
<rbs:parameters>
<stuf:peiltijdstipMaterieel><w>2016-07-08</w></stuf:peiltijdstipMaterieel>
</rbs:parameters>
<rbs:gelijk stuf:entiteittype="NPS">
<bg:geslachtsnaam><w>Jansen</w></bg:geslachtsnaam>
<bg:geboortedatum><w><datum>1973-08-15</datum></w></bg:geboortedatum>
</rbs:gelijk>
</rbs:selectie>
</rbs:zoekNPSOpGeslachtsnaamGeboortedatum>
Op deze manier kun je werken met simpele (REST) berichten hoewel je StUF als specificatietaal op de achtergrond handhaaft. Consumers (met weinig StUF kennis) zullen doorgaans gebruik maken van de compacte berichten zoals het eerste bericht en service providers zullen deze doorgaans vertalen naar generieke (zelf-beschrijvende) StUF-berichten zoals het tweede bericht hierboven.
Dit RFC is opgevoerd in de onderhoudsverzoeken als RFC0447.
De lijst met onderhoudsverzoeken vind je op:
gemmaonline.nl/index.php/StUF-Expertgroep#Documenten
Prima idee om eenvoudige services mogelijk te maken met gebruik making van REST.
In het kader van de duidelijkheid en eenduidigheid pleiten wij er wel zeer dringend voor dat een "eenvoudige REST-service" alleen kan bestaan wanneer ook het parallelle vrije bericht binnen StUF is gedefinieerd.
@Ruud: wat bedoel je met het "parallelle vrije bericht"? Het eerste of het derde bericht in post #1?
We bedoelen hier hetzelfde vrije bericht binnen StUF. Het derde bericht in post #1.
Tijdens de StUF Expertgroep van 15 juni 2016 is aangegeven dat compacte en eenvoudige berichten t.b.v. REST van belang zijn voor bepaalde consumers en een extra faciliteit bieden om een koppelvlak zo elegant mogelijk te maken. Providers moeten service georiënteerd zijn en het consumers zo eenvoudig mogelijk maken. In een koppelvlak wordt uiteindelijk besloten of men alleen het korte bericht, alleen het REST bericht of beiden wil ondersteunen.
Uit de reacties van enkele leden blijkt dat zij nog wat moeite hebben met het idee dat de StUF standaard straks niet alleen meer zou kunnen bestaan uit XML berichten. Zo vroeg Sid Brouwer zich af wat de StUF standaard dan nog eigenlijk is en is hij van mening dat de standaard wordt uitgehold. Als je systeem meerdere koppelvlakken ondersteund dan moet je ook meerdere standaarden ondersteunen.
Ton Timmermans vroeg zich af hoe je dan kunt valideren en Mark Paanakker concludeerde dat een consumer toch StUF berichten terug moet kunnen geven.
Er is besloten dat Henri Korver voorbeelden van compacte berichten gaat maken op basis een vraagbericht waarin een gelijk, scope, start, etc.. zit. Ook gaat hij een voorbeeld maken van een vraagbericht met een wildcard.
Het definiëren van eenvoudige synchrone verzoekberichten, waarvan de functionaliteit wordt gedefinieerd in de vorm van reguliere StUF-berichten, vind ik een goed idee om de volgende redenen:
Het voorschrift dat de berichten vertaalbaar moeten zijn naar een regulier StUF-bericht waarborgt dat een provider zoveel mogelijk reeds bestaande fnctionaliteit voor het afhandelen van StUF-berichten kan hergebruiken.
Het vraagbericht kan wellicht worden vereenvoudigd, maar hoe moet het antwoord er dan uit komen te zien? Als dat gewoon StUF blijft, zal de consumer dit toch moeten interpreteren en is de winst aan de voorkant te verwaarlozen.
Het antwoordbericht blijft een gewoon StUF-bericht, in onderstaand een voorbeeld van een synchroon vrijbericht (Du02) als respons-bericht op de bovenstaande request.
HTTP/1.1 200 OK
<rbs:responsNpsBasis xmlns:stuf="http://www.stufstandaarden.nl/stuf0310" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rbs="http://www.stufstandaarden.nl/koppelvlak/rbs0310" xmlns="http://www.stufstandaarden.nl/sectormodel/bg0320" xsi:schemaLocation="http://www.stufstandaarden.nl/koppelvlak/rbs0310 rbs0100_msg.xsd">
<rbs:antwoord stuf:functie="antwoord">
<rbs:parameters>
<stuf:indicatorHistorie>N</stuf:indicatorHistorie>
</rbs:parameters>
<rbs:persoon stuf:entiteittype="NPS">
<inp.bsn ><w>123456789</w></inp.bsn>
<geslachtsnaam><w>Jansen</w></geslachtsnaam>
<voorvoegselGeslachtsnaam><l>geenWaarde</l></voorvoegselGeslachtsnaam>
...
</rbs:persoon>
</rbs:antwoord>
</rbs:responsNpsBasis>
In een REST-interface hoeft het respons-bericht niet versimpeld te worden omdat je die als een XML-bericht kunt teruggeven. Echter in het request-bericht ben je in een REST-interface verplicht om een GET query string te gebruiken met een platte structuur.
Volgens mij is REST meer dan alleen de requests versimpelen. Als we aan de antwoordkant niets wijzigen, vraag ik me af of we wel echt RESTful bezig zijn. Zoals Erik al aangeeft, vraag ook ik me af wat de winst dan nog is.
Ook vraag ik me af of we nog voldoende informatie in de requests kunnen zetten zonder deze ook complex te maken. Zoals ik tijdens het overleg al aangaf, denk ik dat de voorbeelden wel erg eenvoudig zijn. We hebben in de praktijk vaak te maken met koppelvlakken die ook in samenwerkingsverbanden worden ingezet en die dus wat meer adresseringsgegevens behoeven. Ook het feit dat al deze informatie in een URL komt te staan lijkt mij in het algemeen niet erg wenselijk. Het voorbeeld in de eerste post is hiervan al een aardige illustratie: persoonsgegevens die in de URL komen te staan?!
Ik denk dat we heel goed na moeten denken over REST in zijn geheel.
In deze discussie worden IMO twee zaken door elkaar gehaald: berichten en architectuur. REST is een architectuur waarmee berichten in verschillende formaten verstuurd kunnen worden. De berichten kunnen dus in XML gemaakt worden of in JSON of ??. Zie voor meer informatie bijvoorbeeld https://en.wikipedia.org/wiki/Representational_state_transfer
In de eerste post wordt gesproken over omzetten van REST-berichten (er zijn geen REST-berichten! REST is een architectuur, net als SOAP!) naar generieke (zelfbeschrijvende berichten. Echter, één van de uitgangspunten van REST is dat de berichten zelfbeschrijvend zijn.(bron: https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_in..., punt 3 self-descriptive messages).
In datzelfde voorbeeld wordt een XML bericht vergeleken met een REST aanroep (http GET in dit geval). In het stuk XML opntbreekt echter de de SOAP envelop. De getoonde XML kan dan ook gebruikt worden in een REST architectuur en is niet specifiek voor SOAP.
Vertalen naar een StUF bericht is niet nodig en IMO nodeloos complex: immers, een bericht bevat informatie. Deze informatie moet na inlezen (en technisch toetsen van de structuur van het bericht, parseren) inhoudelijk gecontroleerd worden (kloppen de waarden die in het bericht staan). Het hierbij passende design pattern is Value objects, waarbij de structuur van een informatiemodel als RSGB/RGBZ etc. gehanteerd kan worden. Zie ook http://martinfowler.com/bliki/ValueObject.html en https://en.wikipedia.org/wiki/Value_object . In een compact bericht ontbrekende informatie is niet nodig voor de verwerking van dat bericht. Is die informatie wel nodig is het bericht incorrect en niet compleet.
In de genoemde Value objecten kan de StUF werkwijze (bijvoorbeeld het was-wordt principe bij een kennisgeving met daarin een wijziging) ook gehanteerd worden. Ditzelfde principe kan ook in een JSON bericht opgenomen worden. Wel moet voor elk bericht een definitie opgesteld worden (XSD schema, JSON schema, ?) zodat deze structuur getoetst kan worden.
Met de door KING ingezette beweging richting eindproduct standaarden is het ook veel eenvoudiger om berichten in verschillende formaten zoals XML en JSON te definieren. Immers, in een eindproduct wordt een service met bijbehorende berichten strak gedefinieerd. Hierbij kan dan ook gekozen worden voor SOAP of REST en het te gebruiken bericht formaat.
Liever zou ik een voorstel zien voor een gestandaardiseerde manier van gebruik van REST (en eventuele formaten als JSON) naast de huidige SOAP architectuur. De voor REST benodigde berichtstructuren staan hier dan ook in beschreven. Uitgangspunt van informatieuitwisseling moet altijd het (semantisch) informatiemodel zijn, niet het ene of het andere berichtformaat.
Tijdens de StUF Expertgroep van 21 september 2016 heeft de StUF Expertgroep dit RFC goedgekeurd. Het mag worden uitgewerkt in de StUF standaard.
Hierbij de uitwerking van dit RFC ter goedkeuring tijdens de StUF Expertgroep van 15 februari 2017.
Bijlage
Tijdens de StUF Expertgroep van 15 februari 2017 is de uitwerking van dit RFC goedgekeurd.