Services like Twitter have been around for many years and although some people only use it to watch what’s happening on social media, for some organizations it is a communication channel with their clients. That means that ideally a Twitter stream becomes part of the IT landscape.
Luckily, Twitter has an API that will allow you to make a connection and retrieve the messages that you are interested in or post messages to Twitter. The only thing you need to do is to figure out how to make a connection to Twitter as well as study the API to see which functionality you need.
WSO2 uses connectors to make this easy. A Twitter connector has been available for several years already and by simply adding this connector to your micro integrator you can get a head start and not reinvent the wheel. The recent acquisition of Twitter by Elon Musk has caused unrest and increased the interest in other micro blogging services like for instance Mastodon.
In this blog I’m going to show you how you can create a connection to this service; first using an API and then making a connector out of it. At the time of writing this blog there is no Mastodon connector in the WSO2 connector store. Most of them are written by WSO2 although some are also written by vendors themselves or other people who have a vested interest in the creation of the connector.
One of the first things that you will see is the amount of work that goes into research of the mastodon API and building a full blown connector that encompasses everything that Mastodon offers as far as the API goes.
Creating a new account
Of course, the first thing that you need is an account with Mastodon. I have created the Yenlo account on a Dutch server. It doesn’t really matter where you create the account just click one or select one that is close to your location.
Making the connection
After some research in the documentation, we find that the Mastodon API is secured using oAuth2. This is a very well established standard way of making sure that the user of the API is the real and intended user and not an imposter. In the API manager we used the same concept where we create an application that gives us a client ID and a client secret and from those, we can create an oAuth2 token to grant us access to the API.
Next I’m going to use postman for the creation of the application and the retrieval of the client ID client secret and token.
The API is exposed at /api/v1/apps on the Mastodon server, in my case mastodon.nl. The form data parameters that you need to supply our client name and redirect URIs. Those are the only two mandatory fields, the scopes can be omitted but you will only be granted read access in that case. If everything is correct it will respond with an ID, the name, website, redirect URIs, client-id, client-secret and the vapid key. You can see the call in the screenshot below.
With this data we are able to retrieve a token and start querying the API using the token in the authorization header for the two subsequent API calls.
We add the key as an authorization to the call and search for the account that we just created in order to get the ID and start publishing our first toot.
We make a note of the ID and look in the documentation how we can post something on behalf of the Yenlo user. We can of course always use the regular interface of the browser or the app to post something.
We started by creating an app that gave us a client ID and the client secret. This will allow us to retrieve information that is public; meaning not tied to a specific user. If you want to post something on behalf of our user (in our case of course the Yenlo user), we need to have a different token. The documentation is not quite clear about how that works but with some help from the admins from mastodon.nl I found out that it actually requires a code grant type which of course is a two step OAUTH2 grant type where are you also need to log in.
The first step is that you do a GET request on the authorized URL with parameters client ID, scope, redirect Uri and the response type. It looks something like this [client ID is removed]
https://mastodon.nl/auth/sign_in
When you put this in a browser you’re presented with the following screen. Since we are already logged in on Mastodon we can simply say authorize and we’ll get our new code on the screen that comes after that.
This code is an intermediary step, in the next step we will exchange it for a true token.
To do that we need to do a POST request to the oauth2 server with a number of parameters like client-id, client-secret, the redirect uri, the grant type, the code that we just got and the scopes. I’m using postman to create this API call.
The client ID and client secret we already got when we created the app and the code that we got from the previous step ties the user into the token. So, within this token we also have a link to the user so that we can post something on his or her behalf.
You can also of course use curl, soap UI or any other tool that is able to do rest calls.
When we execute this API we receive an access token that we can add as a header to subsequent API calls, for instance to do a status update.
When you want to post a new status the documentation says that you need to do a POST request to this URL /api/v1/statuses with a bearer token in the header and four required parameters.
I will again use Postman to create this API call.
As you can see the status is added to Mastodon
As we now know how the mechanism works we can make an integration out of it. We will do that in part two of this blog.
Working with the API
When you are working with an API, especially such a big one as the one from Mastodon, clear documentation is key to quickly understand the way the API works. In order to figure this out, it took me some time and help by one of the Mastodon admins (it is a decentralized model).
What is missing is an OpenAPI (aka swagger file) or Postman collection that you can look at and test. There are some user-driven Postman collections but ideally this comes from Mastodon itself.
I also reached out to Colin Domoney from 42 Crunch to get his opinion on this specific API since he is the curator of APIsecurity.io and an expert on the subject of API security, vulnerabilities, breaches and so on. So as a companion article, Colin will look at the security aspects of the API.
It is actually quite strange that in the documentation it says that there are four required parameters and in the example I only added one parameter being the actual status that I wanted to post.
Another strange thing is the fact that the token does not expire. The benefit of OAUTH2 tokens is that they (can) expire after a predefined time. This is the benefit you can compare it to a plastic key card that you get in your hotel. As long as you’re a paying guest it will give you access to your hotel room if you’re not a paying guest anymore or you’re lost your key card it can simply be invalidated so that no access is granted to the person holding the key card. In some older hotels, especially the smaller ones, you still get a real key, If you lose that key, they need to replace it and ideally also replace the lock since somewhere there is now a key to a hotel room that will give you access until you change the lock.
While writing this blog it took me a couple of hours to figure out how Mastodon works with regards to public and private data, the use of the several grant types and in general making everything work. And, to be honest, I barely scratched the surface. You now see how much work goes into setting this up and turning this into a connector. It would be a task that would probably take at least a couple of weeks figuring things out, creating APIs and making everything work in such a way that you can simply integrated it with the micro integrator or enterprise integrator and start working with Mastodon.
