Learning APIs with curl: Posting to social media

To demonstrate how to utilize curl in a real-world scenario, here's a quick example of interacting with a social network platform. Mastodon is an open-source, federated social network and microblogging platform, and features a rich API to read, write, and manage your account. Other social networks may have similar features, and while the exact API commands differ from site to site, Mastodon provides a reasonable example of the process, and in just three simple steps.

If you want to try this process yourself, you must sign up for a Mastodon account (and if you do, be sure to follow the opensource.com bot to see a shell and curl-based bot in action).

[ Read me first: Using curl to interact with an API. ]

Create an app

After creating an account on a Mastodon server, you must create an app hosted by your user. This is done through the website, in the Development panel of your user profile.

Get your API key

After creating a new app, click the app name to see its private credentials. In this case, your credentials include a client key, a client secret, and an authentication token.

This is common regardless of what API you're using. There may only be one API key, or there may be several components, but the point is that you've generated a unique and secret hash that you can use in the program or script that you're using to call on the API.

Learn the API

Learning to talk to an API is exactly the same as learning a new Linux command, a new shell, or a new programming language. You need to know what words are used to structure a command or query, you need to understand the syntax, and you need to know what external information you're required to provide.

Generally, if a service provides an API, it also provides (up-to-date, ideally) documentation on how to use that API. In the case of Mastodon, there's very good documentation on how to interact with your account through the API so that you can learn the language with minimal pain.

Make a post

According to Mastodon's API documentation, you can test your credentials by sending your authorization token, preceded by the string Bearer, as a special header to the API endpoint.

https://mastodon.example/api/v1/accounts/verify_credentials

For example:

$ curl --header 'Authorization: Bearer K90yYtm_1fMxH775bw31-775pnPDZvmQWSJzg' \
https://mastodon.example/api/v1/accounts/verify_credentials

In return, you get a JSON dump of your user profile.

Other API interactions require more information. For example, to post a status to your account, you must also provide form data for the status field:

$ curl --header 'Authorization: Bearer  K90yYtm_1fMxH775bw31-775pnPDZvmQWSJzg' \
--form "status=Test post from curl" \
"https://mastodon.xyz/api/v1/statuses"

Using curl for remote interactions

Coupled with the right API, curl is almost a network programming language. It's easy to use as the courier for your commands, and it has troubleshooting tools built-in. Use curl the next time you need to test or interact with an API.

[ Want to become a curl power user? Check out the curl command cheat sheet. ]