Diensten als Twitter bestaan al vele jaren en hoewel sommige mensen deze dienst alleen gebruiken om te kijken wat er gebeurt op sociale media, dient Twitter voor sommige organisaties als een communicatiekanaal met hun klanten. Dit betekent dat een Twitter-stream idealiter onderdeel wordt van het IT-landschap.
Gelukkig heeft Twitter een API waarmee je een verbinding kunt maken en de berichten kunt ophalen waarin je geïnteresseerd bent of berichten op Twitter kunt plaatsen. Het enige dat u hoeft te doen, is uitzoeken hoe u een verbinding met Twitter kunt maken en de API bestuderen om te zien welke functionaliteit u nodig hebt.
WSO2 gebruikt connectoren om dit gemakkelijk te maken. Er is al enkele jaren een Twitter-connector beschikbaar en door deze connector simpelweg toe te voegen aan uw micro-integrator, kunt u een voorsprong nemen en hoeft u niet opnieuw het wiel uit te vinden. De recente overname van Twitter door Elon Musk heeft voor onrust gezorgd en meer belangstelling gecreëerd voor andere microblogdiensten, zoals Mastodon.
In deze blog laat ik zien hoe u een verbinding kunt maken met deze dienst; door eerst een API te gebruiken en er vervolgens een connector van te maken. Op het moment dat deze blog wordt geschreven, is er geen Mastodon-connector beschikbaar in de WSO2-connectorwinkel. De meeste zijn geschreven door WSO2, hoewel sommige ook zijn geschreven door leveranciers zelf of andere mensen die een gevestigd belang hebben bij het maken van de connector.
Een van de eerste dingen die u zult zien, is de hoeveelheid werk die wordt gestoken in onderzoek naar de Mastodon API en het bouwen van een volwaardige connector die alles omvat wat Mastodon te bieden heeft, voor zover het de API betreft.
Een nieuw account maken
Uiteraard hebt u ten eerste een account bij Mastadon nodig. Ik heb het Yenlo-account gemaakt op een Nederlandse server. Het maakt niet echt uit waar u het account maakt, klik gewoon op een willekeurige optie of selecteer een optie die zich dicht bij uw locatie bevindt.
De verbinding maken
Na wat zoeken in de documentatie, ontdekken we dat de Mastodon API is beveiligd met oAuth2. Dit is een zeer gangbare standaardmanier om ervoor te zorgen dat de gebruiker van de API de echte en beoogde gebruiker is en geen bedrieger. In de API-manager gebruikten we hetzelfde concept waarbij we een applicatie maken die ons een client-ID en een clientgeheim geeft op basis waarvan we een oAuth2-token kunnen maken om ons toegang te geven tot de API.
Vervolgens ga ik Postman gebruiken voor het maken van de applicatie en het ophalen van de client-ID, het clientgeheim en de token.
De API is opengesteld op /api/v1/apps op de Mastodon-server, in mijn geval mastodon.nl. De formuliergegevensparameters die u nodig hebt om onze klantnaam en omleidings-URI’s op te geven. Dit zijn de enige twee verplichte velden, de scopes kunnen worden weggelaten maar u krijgt dan alleen leestoegang. Als alles correct is, wordt er gereageerd met een ID, de naam, de website, omleidings-URI’s, de client-ID, het clientgeheim en de vapid-sleutel. U kunt de oproep zien in de onderstaande schermafbeelding.
Met deze gegevens kunnen we een token ophalen en beginnen met het opvragen van de API met gebruik van de token in de autorisatieheader voor de twee volgende API-aanroepen.
We voegen de sleutel toe als autorisatie aan de oproep en zoeken naar het account dat we zojuist hebben gemaakt om de ID te krijgen en onze eerste toot te publiceren.
We noteren de ID en kijken in de documentatie hoe we namens de Yenlo-gebruiker iets kunnen plaatsen. We kunnen natuurlijk altijd de reguliere interface van de browser of de app gebruiken om iets te plaatsen.
We zijn begonnen met het maken van een app die ons een client-ID en het clientgeheim gaf. Hierdoor kunnen we informatie ophalen die openbaar is; dat wil zeggen niet gebonden aan een specifieke gebruiker. Als u iets wilt plaatsen namens onze gebruiker (in ons geval natuurlijk de Yenlo-gebruiker), hebben we een andere token nodig. De documentatie is niet helemaal duidelijk over hoe dat werkt, maar met wat hulp van de beheerders van mastodon.nl kwam ik erachter dat dit eigenlijk een codetoekenningstype vereist, wat natuurlijk een tweestaps OAUTH2-toekenningstype is waar u ook moet inloggen.
De eerste stap is dat u een GET-verzoek doet op de geautoriseerde URL met parameters client-ID, scope, omleidings-URI en het antwoordtype. Dit ziet er ongeveer zo uit [client-ID is verwijderd]
Wanneer u dit in een browser zet, krijgt u het volgende scherm te zien. Omdat we al zijn ingelogd op Mastodon, kunnen we eenvoudigweg autoriseren aangeven en krijgen we onze nieuwe code op het scherm dat daarna komt.
Deze code is een tussenstap, in de volgende stap gaan we deze omruilen voor een true token.
Om dat te doen, moeten we een POST-verzoek doen aan de oauth2-server met een aantal parameters zoals client-id, clientgeheim, de omleidings-URI, het toekenningstype, de code die we zojuist hebben gekregen en de scopes. Ik gebruik Postman om deze API-aanroep te maken.
De client-ID en het clientgeheim die we al kregen toen we de app maakten en de code die we uit de vorige stap kregen, verbindt de gebruiker met de token. Binnen deze token hebben we dus ook een link naar de gebruiker, zodat we namens hem of haar iets kunnen plaatsen.
U kunt natuurlijk ook curl, soap UI of een andere tool gebruiken die rest-oproepen kan doen.
Wanneer we deze API uitvoeren, ontvangen we een toegangstoken die we als header kunnen toevoegen aan volgende API-aanroepen, bijvoorbeeld om een statusupdate uit te voeren.
Als u een nieuwe status wilt plaatsen, geeft de documentatie aan dat u een POST-verzoek moet doen naar deze URL: /api/v1/statuses met een dragertoken in de header en vier vereiste parameters.
Ik zal Postman opnieuw gebruiken om deze API-aanroep te maken.
Zoals u kunt zien is de status toegevoegd aan Mastodon.
Nu we weten hoe het mechanisme werkt, kunnen we er een integratie van maken. Dat doen we in deel twee van deze blog.
Werken met de API
Wanneer u met een API werkt, vooral een grote als die van Mastodon, is duidelijke documentatie essentieel om snel te begrijpen hoe de API werkt. Het kostte me wat tijd en hulp van een van de Mastodon-beheerders om dit uit te zoeken (het is een gedecentraliseerd model).
Wat ontbreekt is een OpenAPI (ook wel swagger-bestand genoemd) of Postman-verzameling die u kunt bekijken en testen. Er zijn enkele door gebruikers aangestuurde Postman-verzamelingen, maar idealiter komt deze van Mastodon zelf.
Ik heb ook contact opgenomen met Colin Domoney van 42 Crunch om zijn mening over deze specifieke API te krijgen, aangezien hij de beheerder is van APIsecurity.io en een expert op het gebied van API-beveiliging, kwetsbaarheden, inbreuken enzovoort. Dus als begeleidend artikel zal Colin kijken naar de beveiligingsaspecten van de API.
Het is eigenlijk best vreemd dat er in de documentatie staat dat er vier vereiste parameters zijn en ik in het voorbeeld slechts één parameter heb toegevoegd, namelijk de werkelijke status die ik wilde plaatsen.
Wat ook vreemd is, is het feit dat de token niet verloopt. Het voordeel van OAUTH2-tokens is dat ze na een vooraf bepaalde tijd (kunnen) verlopen. Dit is het voordeel dat u kunt vergelijken met een plastic keycard die u in een hotel krijgt. Zolang u een betalende gast bent, hebt u toegang tot uw hotelkamer. Als u geen betalende gast meer bent of als u uw keycard kwijt bent, kan deze eenvoudig ongeldig worden gemaakt, zodat er geen toegang wordt verleend aan de houder van de keycard. In sommige oudere hotels, vooral de kleinschalige, krijgt u nog steeds een echte sleutel. Als u die sleutel verliest, moet het hotel deze sleutel en idealiter ook het slot vervangen, aangezien er nu ergens een sleutel is van een hotelkamer die u toegang geeft tot het slot is veranderd.
Tijdens het schrijven van deze blog kostte het me een paar uur om erachter te komen hoe Mastodon werkt met betrekking tot openbare en privégegevens, het gebruik van de verschillende toekenningstypen en in het algemeen om alles te laten werken. En om eerlijk te zijn, begrijp ik nog lang niet alles. U ziet nu hoeveel werk het kost om dit in te stellen en er een connector van te maken. Het kost waarschijnlijk minstens een paar weken om dingen uit te zoeken, API’s te maken en alles zo te laten werken dat je het eenvoudig kunt integreren met de Micro-integrator of Enterprise-integrator en aan de slag kunt gaan met Mastodon.
