In de vorige twee delen van deze blog hebben we een API ontwikkeld waarmee we een gedigitaliseerde afbeelding uit het Rijksmuseum kunnen ophalen en lokaal kunnen opslaan. Voor dit volgende deel gaan we die integratie uitbreiden door het naar de Meural API te sturen om de afbeelding op ons digitale canvas te krijgen.
Om de blog binnen een redelijke omvang te houden, implementeer ik niet alles wat je normaal gesproken nodig zou hebben als je dit in het echt zou doen.
Specifiek implementeer ik de oproep om een token te verkrijgen, wat nodig is wanneer je iets uploadt naar je eigen Meural, niet. En ik implementeer ook niet alle aanvullende mogelijkheden die de API heeft met betrekking tot het maken van collecties en dat soort zaken.
Wat ik wel doe, is de kunstwerken uploaden, zodat ze beschikbaar zijn op het mobiele apparaat en vanaf het mobiele apparaat selecteer ik de afbeeldingen en stuur ik ze naar het canvas.
Ik kan me voorstellen dat je geen Meural Canvas 2 hebt. In dat geval zou het moeilijk zijn om mee te doen, maar over het algemeen is het ook waardevol om te weten hoe je een berichtinhoud kunt wijzigen om een verbinding te maken met een API zoals die van Meural.
De opstelling
Even een samenvatting van wat je nodig hebt als je dit zelf wilt proberen:
- Een versie van de Micro Integrator (Ik gebruik versie 4.2.0)
- Integration Studio om de artefacten te ontwikkelen die we gaan implementeren (ik gebruik versie 8.2)
- Een API-sleutel van het Rijksmuseum om hun API te kunnen gebruiken
- Een Meural als je de volledige flow wilt hebben. Zo niet, dan kun je de afbeelding lokaal opslaan.
Wat hebben we
Op dit moment hebben we een API die in staat is om een aantal objectnummers te ontvangen die overeenkomen met een digitaal kunstwerk zoals een schilderij of een tekening uit de Rijksstudio. De API zal door de herhalende elementen van de berichtinhoud itereren (in dit geval de objectnummers), voor elk van deze nummers zal het proberen informatie over het object op te halen en een download-URL waar we het bestand daadwerkelijk kunnen downloaden. Dit bestand wordt vervolgens lokaal op onze schijf opgeslagen en in de laatste stap zullen we dat bestand naar de Meural API sturen.
Ik heb een deel van de bemiddeling die ik in de vorige blogs heb behandeld eigenlijk weggelaten, omdat dat niet is veranderd. Je ziet de drie puntjes <…> </…> in de code waar ik stukken heb weggelaten. Ik heb ook wijzigingen aangebracht in de inspringing om meer op één regel te passen en het token dat werd gebruikt, evenals de sleutel om de oorspronkelijke informatie van het Rijksmuseum op te halen, verwijderd.
Wat is er nieuw?
Wat ik heb gedaan, is een nieuwe eigenschap geïntroduceerd die het aantal elementen in de array telt. Deze eigenschap json-eval($.object.length()) slaat de waarde op in een eigenschap genaamd ’totalobjects’ en die waarde wordt na de iteratie geretourneerd in een aangepaste berichtinhoud die het aantal verwerkte objecten aangeeft.
<?xml version="1.0" encoding="UTF-8"?>
<api context="/art" name="Meural" xmlns="http://ws.apache.org/ns/synapse">
<resource methods="POST">
<inSequence>
<property expression="json-eval($.object.length())" name="totalobjects" scope="default" type="STRING"/>
<iterate attachPath="json-eval($.object)" continueParent="true" expression="json-eval($.object)" id="it1" preservePayload="true" sequential="true">
<target>
<sequence>
<...> </...>
<property expression="fn:concat('/opt/wso2/Downloads/',get-property('objectnr'),'.jpg')" name="fp" scope="default" type="STRING"/>
<enrich>
<source clone="false" type="body"/>
<target property="ORIGINAL_PAYLOAD" type="property"/>
</enrich>
<file.write configKey="FC1">
<...> </...>
</file.write>
<enrich>
<source clone="false" property="ORIGINAL_PAYLOAD" type="property"/>
<target type="body"/>
</enrich>
<property name="DECODE_MULTIPART_DATA" scope="axis2" type="BOOLEAN" value="true"/>
<property expression="//ns:binary" name="Message" scope="default" type="STRING" xmlns:ns="http://ws.apache.org/commons/ns/payload"/>
<payloadFactory media-type="xml">
<format>
<root xmlns="">
<file Content-Type="image/jpeg" filename="$1" name="image" xmlns="http://org.apache.axis2/xsd/form-data">$2</file>
</root>
</format>
<args>
<arg evaluator="xml" expression="$ctx:fp"/>
<arg evaluator="xml" expression="get-property('Message')"/>
</args>
</payloadFactory>
<property name="messageType" scope="axis2" type="STRING" value="multipart/form-data"/>
<header name="Content-Type" scope="transport" value="multipart/form-data"/
<property name="DISABLE_CHUNKING" scope="axis2" type="STRING" value="true"/>
<header name="Authorization" scope="transport" value="Token {TOKEN]"/>
<call blocking="true">
<endpoint>
<http method="post" uri-template="https://api.meural.com/v0/items">
<...> </...>
</http>
</endpoint>
</call>
<drop/>
</sequence>
</target>
</iterate>
<property expression="count(//retrieve/object)" name="TotalElements" scope="default" type="STRING"/>
<payloadFactory media-type="json">
<format>{"Message" : "$1 Images uploaded"}</format>
<args>
<arg evaluator="xml" expression="get-property('totalobjects')" literal="true"/>
</args>
</payloadFactory>
<respond/>
</inSequence>
<outSequence/>
<faultSequence/>
/resource>
</api>
Ik heb een nieuwe mediator geïntroduceerd, de ‘enrich’ mediator, om de oorspronkelijke berichtinhoud op te slaan die we van het Rijksmuseum hebben ontvangen. Dit doe ik omdat ik de berichtinhoud niet wil verliezen wanneer de bestandsconnector deze overschrijft met zijn reactie. Dus de ‘enrich’ mediator slaat de berichtinhoud op in een eigenschap, we gaan verder met de bemiddeling en wanneer we klaar zijn en in dit geval geen acties met de berichtinhoud hoeven te doen die mogelijk door de bestandsconnector is gemaakt, herstellen we de oorspronkelijke berichtinhoud vanuit de eigenschap om deze te gebruiken.
De volgende bemiddelingssequentie wordt deels bepaald door wat de API van Meural verwacht en deels door de werking van de Micro Integrator in dit geval.
Met de ‘property’ mediator stel ik twee waarden in die nodig zijn. Ik stel DECODE_MULTIPART_DATA in op true zodat we het bericht niet coderen en stel de eigenschap Message in op binair. De volgende stap gebruikt de ‘payloadFactory’ mediator om een bericht te maken dat door de Meural API wordt vereist.
Binnen die ‘payloadFactory’ mediator zie je twee waarden die beginnen met het $-teken, $1 en $2. Deze worden gevuld met de argumenten die je onder de ‘format’-sectie vindt. De eerste is de bestandsnaam en de tweede is het berichttype.
Er volgen nog drie regels bemiddeling waarin het contenttype wordt ingesteld op multipart/form-data, DISABLE_CHUNKING door het in te stellen op true en tot slot wordt de token toegevoegd aan de header om deze API-oproep te authenticeren.
Ik heb de token verwijderd omdat het gevoelige informatie is en nooit gedeeld mag worden, zelfs niet als deze is verlopen. Een verlopen token kan niet worden gebruikt, maar over het algemeen is het een goed idee om nooit tokens, client keys, client secrets of API-sleutels te delen. Door ze op geen enkel moment te delen, verklein je de kans op fouten, per ongeluk delen, enzovoort.
Bericht verwijderen
Aan het einde van de bemiddeling van de iteratiemediator zie je dat we eigenlijk het bericht hebben verwijderd omdat we niet geïnteresseerd zijn in de reactie van de Meural API. We gaan ervan uit dat alles correct is en we doen niets op het gebied van foutafhandeling.
In het echte scenario moet je hier natuurlijk rekening mee houden en ervoor zorgen dat je de foutafhandeling op de juiste manier doet.
Maar dit is het mooie van het schrijven van een blog, we kunnen het een beetje abstract maken en hoeven ons geen zorgen te maken over elk denkbaar scenario.
Wanneer we klaar zijn met itereren door de JSON-array, gaat de bemiddeling verder met de volgende regel die ons een totaal geeft van het aantal objecten dat is opgehaald en uploadt het naar de Meural API.
Dit is de waarde waarmee we zijn begonnen toen het bericht binnenkwam bij de API, waar we het aantal elementen hebben geteld.
Wat ik nu heb in mijn Meural-app zijn een groot aantal kunstwerken die ik nu naar het canvas kan sturen. Dit kan ik ook automatiseren, maar voor deze blog houd ik het handmatig. Anders zou ik eindigen met delen 4 en 5 als ik niet voorzichtig ben. Je kunt de s met de kunstwerken vinden op Yenlo Bitbucket.
Je kunt zien dat integratie niet alleen voor kunstenaars is, maar voor bijna elke ontwikkelaar. Je kunt de benodigde integratie ontwikkelen om de Rijksstudio met Meural te verbinden, maar anderen kunnen dat ook doen.
Voor Meural kan dit deel uitmaken van hun abonnement op gecureerde kunst die ze maandelijks of jaarlijks aanbieden. Dus er is een winst voor Meural/Netgear om dit soort verbindingen met museumbronnen rechtstreeks te ontwikkelen. Voor het Rijksmuseum kan het definiëren van een knop op de site om rechtstreeks naar de Meural van een gebruiker te sturen mensen in staat stellen meer van kunst te genieten met bijna geen werk. Het zal de betrokkenheid bij de Rijksstudio vergroten. Ze kunnen gedigitaliseerde afbeeldingen van tentoonstellingen die mensen hebben bezocht naar de Meural thuis sturen. De sky is the limit. Dat is wat ik noem: Digitale verbeelding.
Digitale verbeelding
Ik ga ook kijken naar wat je kunt doen met een API zoals deze, gezien het feit dat veel bronnen een API-interface hebben en het eigenlijk vrij eenvoudig is om er een verbinding mee te maken.
Ik heb het niet alleen over musea en hun collectie kunst, maar ook over de Google Photos API waar je wellicht al je vakantiekiekjes hebt opgeslagen.
Het mechanisme dat ik laat zien in deze blogs in delen 1-2 en 3 kan ook worden toegepast op de Google API.
Natuurlijk zullen er wijzigingen zijn die je moet aanbrengen, omdat niet elke API hetzelfde is.
Integendeel, organisaties hebben veel vrijheid om APIs te maken in welke vorm dan ook. Natuurlijk zijn er puristen die een zeer beperkte visie hebben op wat een API is, maar uiteindelijk is het niet aan de puristen. Het is aan de organisatie, de architecten en de ontwikkelaars om te bepalen hoe ze de APIs gaan opzetten, richtlijnen voor benamingen en andere richtlijnen vast te stellen.
Beveiliging
Wat betreft beveiliging denk ik dat er nog veel te doen is om APIs veiliger te maken, omdat APIs de toegangspoort vormen tot de diensten die je als organisatie aanbiedt en je kunt er zeker van zijn dat je API zal worden aangevallen. Een API-beheeroplossing in combinatie met schemavalidatie met behulp van OpenAPI 3.0-beschrijvingen zal je APIs veiliger maken. Maar het is ook een kwestie van ervoor zorgen dat alle systemen up-to-date zijn, zodat er geen kwetsbaarheden zijn die niet zijn gepatcht, maar ook dat het transport tussen de persoon die de API aanroept en de backend veilig is.
Met betrekking tot dat, vanuit het perspectief van de backend, bekijk de OWASP 2023-lijst met beveiligingskwetsbaarheden. Het zal je de meest voorkomende fouten laten zien die mensen maken bij het maken van een API met betrekking tot de frontend. Een API-beheeroplossing is naar mijn mening een must voor elke organisatie die APIs en zichzelf serieus neemt. Uiteindelijk is beveiliging geen bijzaak, maar een principe dat vanaf het begin moet worden toegepast.
