Sommige mensen zeggen dat integratie een kunstvorm is. Daar ben ik het niet mee eens! Zeggen dat integratie een kunstvorm is, betekent dat je een kunstenaar moet zijn om systemen te kunnen integreren. Ik heb geen probleem met kunstenaars, omdat ik geloof dat een echte kunstenaar een buitengewoon persoon is in haar of zijn vakgebied, maar ik heb wel moeite met het idee dat je een kunstenaar moet zijn om te kunnen integreren. Omdat niet iedereen een kunstenaar kan zijn, is het slechts voor een zeer selecte groep mensen.
Terwijl iedereen kan integreren. Vertrouw me, als trainer die meer dan duizend mensen heeft opgeleid, weet ik dat niet alleen kunstenaars systemen kunnen integreren.
Maar er is een woord met dat een link heeft met ‘kunst’ dat wel van toepassing is op mensen die systemen integreren. Dat woord is ‘ambachtsman’. Als het woord onbekend voor je is, zoek het op in een woordenboek, ik kwam een mooie uitleg tegen wat ze zijn, ambachtslieden, en ik citeer:
“Ambachtslieden zijn niet hetzelfde als kunstenaars, maar het kan soms moeilijk zijn om het verschil te zien. In de Middeleeuwen organiseerden ambachtslieden zich in gilden. In elke stad had elke groep ambachtslieden – zoals wevers, timmerlieden, schoenmakers, enzovoort – zijn eigen gilde. Deze gilden waren verantwoordelijk voor het vaststellen van lonen en prijzen, het handhaven van hoge normen en het beschermen van hun leden tegen externe concurrentie.”
Ik geloof wel dat integratie past bij de definitie van ambachtsman. Je kunt een leerling worden om een integratie-ambachtsman te worden
Je zou kunnen vragen waarom ik het nu over kunst en integratie heb? Dat is een zeer goede vraag en een die heel eenvoudig te beantwoorden is.
En hiermee bedoel ik dat ik kunst die beschikbaar is op de website van het Rijksmuseum in Nederland, download en deze naar het digitale canvas Meural 2 van Netgear stuur. De grote meesters hangen nu bij mij aan de muur.
Meural
Voor degenen die niet bekend zijn met Meural, kun je het zien als een digitaal canvas. Het lijkt op digitale fotolijsten die populair waren aan het begin van de 21e eeuw, maar in dit geval zijn ze groter, tot 16 x 24 inch (40 x 60 cm) of 19 x 29 inch (48 x 74 cm).
Het heeft een internetverbinding, een bijbehorende app en een API waarmee je kunst die je online kunt downloaden, op je eigen canvas kunt plaatsen. Of zelfs de foto’s die je hebt genomen tijdens je vakantie en deze ook kunt tonen.
Met de app op mijn mobiele telefoon kon ik al foto’s downloaden van de website van het Rijksmuseum en ze uploaden naar het canvas om te worden weergegeven.
Ik zou dit echter graag doen vanuit een programma dat ik zelf beheer. In deze blog zal ik uitleggen hoe je zo’n integratie kunt uitvoeren, waarbij bronnen van de ene kant naar een digitaal canvas worden overgebracht.
Een andere reden om dit te doen is dat ik vaak merk dat mensen denken dat integratie beperkt is tot het uitwisselen van XML- of JSON-payloads. Dat is niet waar. De Micro Integrator van WSO2 is in staat om allerlei soorten bestanden te verwerken, zelfs binaire bestanden, zoals ik zal laten zien.
De installatie
Om de integratie uit te leggen en zodat je het kunt volgen op je eigen machine, heb je een aantal dingen nodig:
- Een versie van de Micro Integrator (Ik gebruik versie 4.2.0)
- Integration Studio om de artifacts te ontwikkelen die we gaan implementeren (ik gebruik versie 8.2).
- Een API-key van het Rijksmuseum om hun API te kunnen gebruiken.
- Een Meural-canvas als je de volledige workflow wilt hebben. Zo niet, dan kun je de afbeelding lokaal opslaan.
WSO2
Het installeren van WSO2 is vrij eenvoudig. Download gewoon de Micro Integrator en Integration Studio van de website van WSO2. Zorg ervoor dat je de juiste versie van Java geïnstalleerd hebt (bijvoorbeeld OpenJDK 11) en doe enkele kleine configuraties, zoals het instellen van JAVA_HOME en ervoor zorgen dat Java toegankelijk is via het pad en correct is ingesteld.
Ik heb een aantal blogs geschreven over het opzetten van WSO2 op zowel Windows als Linux, en natuurlijk kun je altijd deelnemen aan een van de trainingen waar je praktische ervaring kunt opdoen met het doen van deze configuratie.
Integration Studio is een aanvullende download van dezelfde pagina waar je de Micro Integrator hebt gedownload, maar iets lager op de pagina. Integration Studio is een plug-in bovenop Eclipse, en voor degenen die bekend zijn met Eclipse zal het geen probleem zijn om ermee te werken.
Zelfs als je een beginner bent, is Integration Studio een goede tool om te gebruiken omdat het je in staat stelt om een hoog niveau grafische structuur van een proxy of een API te maken, wat handig is als je nieuw bent in integratieprogrammering. Daarom gebruik ik het ook in onze trainingsmodules voor de Micro Integrator als ontwikkelomgeving voor al onze labs.
Rijksmuseum
Een ander iets dat we moeten doen, is een key krijgen voor de collectie die is opgeslagen in de Rijksstudio. Maak je eigen account aan met een gebruikersnaam, e-mailadres en wachtwoord en log in op de Rijksstudio-omgeving. Als je wilt, kun je zelfs inloggen met je Facebook-account.
Je moet je e-mailadres bevestigen. Dit kan enkele minuten duren voordat de e-mail aankomt. Wanneer je bent ingelogd en op je icoon klikt (in ons geval een Y), zie je een tandwielpictogram, klik daarop.
Scroll naar beneden en ga naar het gedeelte Rijksmuseum API. Vul het beoogde gebruik in en klik op “Request a key”. Dit wordt naar je gemaild op het opgegeven e-mailadres.
De sleutel uit de e-mail is de API-sleutel die we zullen gebruiken in het GET-verzoek om kunstwerken op te halen. In tegenstelling tot wat de website zegt, krijg je alleen een sleutel in de e-mail. Er is echter ook een link naar de API-documentatie. Dit is handig als je wilt weten wat je nog meer kunt doen met de API, welke bronnen beschikbaar zijn, enzovoort. Voor deze blog gaan we echter niet te diep in op de documentatie, maar we gaan meteen focussen op wat we willen doen, namelijk het ophalen van een gedigitaliseerd meesterwerk.
De API die het Rijksmuseum blootstelt, maakt gebruik van een zeer bekende methode om informatie op te halen, namelijk door een HTTP GET-verzoek te doen naar een specifieke bron. Aangezien we de sleutel aan de URL toevoegen als parameter, kunnen we dat eigenlijk doen vanuit de browser, wat het gemakkelijker maakt om je te laten zien wat voor soort response we krijgen.
Maar laten we eerst eens kijken naar de URL die we moeten gebruiken. Als we door de API-documentatie graven, laat deze pagina ons precies zien wat we nodig hebben. De Collections details API stelt ons in staat om een GET-verzoek te doen met een aantal parameters, zoals je kunt zien in de onderstaande afbeelding. Parameters zijn de sleutel, het formaat, de cultuur en het objectnummer. In het rode rechthoekige vakje zie je een voorbeeldverzoek zonder de API-sleutel om het beroemdste meesterwerk van Rembrandt, de Nachtwacht, op te halen:
https://www.rijksmuseum.nl/api/nl/collection/SK-C-5?key=[api-key]
Als je de [api-sleutel] vervangt door jouw API-sleutel, zie je de response.
Zoals eerder vermeld, kun je de URL ook in een browser invoeren en krijg je deze response te zien.
Ik heb eigenlijk de URL gemarkeerd, evenals delen van de JSON-response waarin we geïnteresseerd zijn. Het interessante is dat de URL die daar wordt getoond eigenlijk de plek is waar je de afbeelding kunt downloaden en op je lokale schijf kunt opslaan. De APIkey is niet leesbaar gemaakt omdat je deze altijd zo veel mogelijk afschermt.
Als je de URL kopieert en in de browser plakt, zie je het resultaat.
In deze blog ga ik de integratie in kleine stukjes knippen en we zullen eerst kijken hoe we een integratie kunnen maken om de informatie van het gedigitaliseerde beeld van het meesterwerk op te halen.
Het maken van de API
Ik ga een API gebruiken om de verbinding te maken. Dit klinkt misschien logisch, aangezien API’s de meest voorkomende manier zijn om verbinding te maken, maar het mooie van een enterprise service bus-oplossing zoals de Micro Integrator is dat het verschillende berichttypen kan verwerken, zoals een SOAP-bericht en dit naar een API kan sturen.
Maar ik ga gewoon een API gebruiken. Om deze blog beknopt te houden, zal ik niet elke stap uitleggen die je moet nemen om met Integration Studio te werken. Ik zal de belangrijkste stappen laten zien, maar ik zal niet alle schermafbeeldingen en configuraties tonen die je normaal gesproken zou moeten doen bij het maken van een integratieproject op de Micro Integrator.
De eerste stap is het maken van een integratieproject en zoals je kunt zien op de schermafbeelding, neem ik de standaardinstellingen over, maar voeg ik ook een connector subproject toe, omdat we dit later nodig hebben.
Wat betreft de API, ik ga de API configureren met de HTTP-verb POST, dus het vereist een payload waarin we de objectnummers van de schilderijen die we willen ophalen en gebruiken kunnen doorgeven. Wanneer we de API van het Rijksmuseum aanroepen, zal het eigenlijk een GET HTTP-verb zijn, omdat dat is wat het museum ons toestaat, het ophalen van informatie.
Als GET en POST je niet zo veel zeggen, lees dan mijn artikel “What is an API” waarin ik APIs in het Engels uitleg.
De API zelf is vrij eenvoudig en ik houd het bewust zo eenvoudig mogelijk. Dat betekent dat een deel hard gecodeerd is, bijvoorbeeld in plaats van een endpoint in een apart artefact, heb ik deze nu in de code gezet. Maar wat doen we nu qua integratie?
Het eerste dat gebeurt in de property “objectnr” is dat we de binnenkomende waarde toewijzen.
Vervolgens gaan we het endpoint samenvoegen, waarbij we het objectnummer eenvoudigweg tussen het webadres en de API-sleutel plaatsen.
We roepen het eindpunt aan met de Uri-template en zoals we kunnen zien in de screenshot van SoapUI, krijgen we een response terug.
In de laatste property halen we de URL op waar we de afbeelding kunnen downloaden, en met die URL gaan we deze later downloaden. Met de log Mediator toon ik deze op het console.
<?xml version="1.0" encoding="UTF-8"?>
<api context="/art" name="MeuralAPI" xmlns="http://ws.apache.org/ns/synapse">
<resource methods="POST">
<inSequence>
<property expression="json-eval($.object)" name="objectnr" scope="default" type="STRING"/>
<property expression="fn:concat('https://www.rijksmuseum.nl/api/en/collection/',//object,'?key=Z6sfcxEM')" name="uri.var.rmaddress" scope="default" type="STRING"/>
<call>
<endpoint name="RM">
<http method="get" uri-template="{uri.var.rmaddress}">
<suspendOnFailure>
<initialDuration>-1</initialDuration>
<progressionFactor>1</progressionFactor>
</suspendOnFailure>
<markForSuspension>
<retriesBeforeSuspension>0</retriesBeforeSuspension>
</markForSuspension>
</http>
</endpoint>
</call>
<property expression="json-eval($.artObject.webImage.url)" name="uri.var.imageurl" scope="default" type="STRING"/>
<log level="custom">
<property expression="get-property('uri.var.imageurl')" name="url"/>
</log>
<respond/>
</inSequence>
<outSequence/>
<faultSequence/>
</resource>
</api>
Ik heb een JSON-payload gemaakt, {“object”: “SK-C-5”}, die ik doorgeef aan de API.
Dat is genoeg voor deze blog. In deel 2, ga ik zorgen dat er een JSON-array wordt ondersteund en verwerkt, en we gaan daadwerkelijk de afbeeldingen downloaden en opslaan.
