Wat betekenen de REST & SOAP API voor xential?

Stel je voor dat systemen met elkaar moeten praten. Daar is een generieke taal voor bedacht: STUF-dcr, REST en SOAP. Laten we beginnen bij het begin. REST en SOAP bij xential houdt in dat een communicatie laag, REST of SOAP in dit geval, een call doet waarbij er informatie wordt opgevraagd en een actie uitgevoerd wordt. Een concreet voorbeeld is wanneer een zaaksysteem sjabloon X opvraagt bij xential. Dit gebeurt door middel van een API. Die vult vervolgens de opgevraagde data in en geeft als antwoord naar zaaksysteem een .docx of een .pdf terug op deze plek. Dit bestaat uit een call, action en endpoint. Het action-gedeelte is waar onze API heel goed in is.

Wat is nou een API?
Een API is een Application Programming Interface. Het is platgezegd een ingang tussen systemen en software naar een ander systeem. Zo kunnen ze met elkaar communiceren en gegevens uitwisselen. Om het even in een concreet voorbeeld te gieten: een stekkerdoos is in dit geval het systeem of de software en de stekker is de API. Wereldwijd zijn er verschillende stekkers, die niet overal inpassen. Als ze wel passen, kunnen ze dus met elkaar praten. Dat gebeurt door middel van een API.

Veelgebruikte API’s
Op dit moment zijn de twee meest gebruikte de REST en SOAP API. SOAP (Simple Object Access Protocol) API is een koppeling waarin strakke afspraken worden gemaakt hoe deze eruit ziet voor structuur en controle en hoe deze gebruikt moet worden. Deze is ook zwaarder dan de REST API. REST (Representational State Transfer) API is een stuk lichter, omdat deze zonder contract wordt gebruikt. Door de ontbrekende structuur kan het ingewikkelder zijn deze te ontwikkelen.

Hans Lankamp, manager Sales en Gerco Seppenwoolde, technisch partner manager vertellen je over wat deze API’s voor xential betekenen.

Kaders van REST & SOAP
Tegenwoordig wordt er veel gebruik gemaakt van REST. Dat komt doordat het de nieuwste techniek is. Hoe zit het dan met de kaders die zo’n API mee krijgt? Bij SOAP gaat er in de aanvraag een header mee. In deze header worden verwachtingen vastgelegd en acties en is er minder ruimte voor een eigen antwoord. Dat antwoord komt terug als XML. Bij REST heeft de aanvrager meer flexibiliteit om een eigen antwoord terug te geven in JSON-vorm.

Hans: “‘Vroeger’ hadden we alleen de keuze uit SOAP en StUF-DCR óf een leverancierskoppeling. Zo’n leverancierskoppeling is ook heel onderhoudsintensief, dus hier zijn we in gaan minderen. Tegenwoordig kennen we dus ook REST, waardoor we kunnen kiezen op basis van wensen en systemen van de klant.”

Gemeente Rotterdam
Een mooi voorbeeld van de huidige situatie, is de Gemeente Rotterdam. Wij hebben 1 stekker (Enterprise Service Bus) die we voor bijvoorbeeld 25 systemen tegelijk inzetten. Dus 1 API die met 25 systemen kan praten. Bij de Gemeente Rotterdam hebben we 1 API die met verschillende afdelingen communiceert. Op deze manier hoeven zij maar 1 keer te investeren in het bouwen hiervan en hebben wij minder onderhoud. Een win-winsituatie dus. Dit is het universele alternatief van een leverancierskoppeling én het is toekomstbestendig. Toekomstbestendig zeggen we, omdat wanneer zij bijvoorbeeld overstappen naar een ander zaaksysteem, er geen nieuwe koppeling hoeft te worden gemaakt.

Totstandkoming van koppelingen
IT-Ops heeft een iets andere rol in dit verhaal. Gerco Seppenwoolde helpt partners om de koppelingen tot stand te brengen door middel van de berichtgeving die naar xential toe komt. Daarnaast helpt hij aan de start van een project met het bepalen van de juiste koppeling en zet hij daarna de testomgeving klaar. De verbinding tussen de systemen wordt beveiligd op basis van certificaten, eventueel een IP-blokkade en het rechten systeem binnen xential. Vanuit de interface kan een document opgebouwd worden als een xential gebruiker, zonder dat daar gegevens van bekend zijn binnen een ander systeem door het impersoneren van gebruikers. Hierbij wordt er met een standaard interface gebruiker (zonder verdere rechten) het berichten verkeer afgehandeld, maar wordt het document met de rechten van een ‘echte’ gebruiker opgesteld.

Om de koppeling te bouwen, op basis van de standaard API, is belangrijk dat het werkproces van de klant duidelijk is. Hierbij is belangrijk waar en in welk formaat het document afgeleverd moet worden. Daarnaast is het ook mogelijk om meerdere dezelfde documenten met bijvoorbeeld verschillende adressen in 1 handeling af te leveren of extra headers toe te voegen aan het aflever bericht zodat het ontvangende systeem op basis van deze informatie bepaalde acties kan uitvoeren.

Wanneer adviseer je nou wat?
Het verschil in REST en SOAP ziet Gerco voornamelijk in het verschil in techniek. SOAP is wat verouderd, maar het resultaat is wel ongeveer gelijk. REST is vanwege de techniek duurzamer en iets geavanceerder qua veiligheid. Als gebruiker merk je geen verschil hierin. Je drukt namelijk op de knop om een document samen te stellen en de API zorgt er ‘silent’ voor dat dit gebeurt. Die silent actie is vooraf ingesteld, door in dit geval Gerco. Hij geeft de kaders mee waaraan bepaalde ‘actions’ moeten voldoen. Afhankelijk van de API komt dit dus terug in JSON of XML berichten. Gerco: “Je kunt die silent actie met kaders zien als een soort route waarbij knooppunten moeten worden afgevinkt. Als je dat goed doet, komt er geen gebruiker aan te pas en wordt jouw document gegenereerd. In het geval dat er tóch iets ontbreekt wordt voor de gebruiker de xential gebruikersinterface geopend in de browser om het document aan te vullen. In beide gevallen wordt het document terug geleverd op een vooraf ingesteld eindpunt.”