Using Plume's REST API

This evening I decided to fall a little deeper down the fediverse rabbit hole and decided to check out Plume. So far, I like it. It’s super minimal and easy to get started. Before even creating the account though, I started looking at the documentation. Sitting right at the top of the list is “API Documentation”. Okay let’s give it a go.

First Impressions

Remember when I called it minimal? Yeah that applies to the API as well. Just about all you can do is authenticate, query for posts, and create posts. But hey, what else do you really need for a blog? Let’s try to get authenticated.

Creating an app

The first step to getting an oauth2 token is to create an app. I feel like the documentation can be improved a little here but after looking at the code I was able to figure out that all I needed to create an app was to give it a name. Here’s the curl command I used to create my app:

curl -X POST 'https://fediverse.blog/api/v1/apps' -d $'{"name": "Pats Blog"}'

That should give you a JSON response that contains some information about your app. The most important being the client_id and client_secret. Keep those around, you’re going to need them to get a token.

Getting an oauth token

Next we need to use the client ID and secret to get a token. The curl request I used for that was:

curl "https://fediverse.blog/api/v1/oauth2?client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scopes=read+write&username=patoconnor43&password=$PLUME_PASSWORD"

Use your own variables to fill in the request.

That should give you a token that you can use to make requests.

Getting some posts

The first request I tried to make was to get the posts on my own blog or at least that’s what I thought I was doing. The request I made was:

curl 'https://fediverse.blog/api/v1/posts' -X GET -H "Authorization: Bearer $PLUME_TOKEN"

I think what this actually does is ask Plume to give me every single post in the database. I’m only making an assumption here but this request hung until I killed it. I didn’t connect the dots that I was asking for everything until I made this request:

curl 'https://fediverse.blog/api/v1/posts?title=Test' -X GET -H "Authorization: Bearer $PLUME_TOKEN"

This was the title of my post but I also got back quite a few more posts from the instance.

Okay well that’s fine and also makes sense. It’s pretty cool that I can search through all the posts on the instance.

Creating a post?

Finally we get to the what I really wanted to do with the API. Can I create a post? First, I’ll give you a little more context about I was thinking about trying to do. I love writing markdown in Neovim. It’s a real comfy environment for me and I’d like to be able to do all my writing in Neovim. I’m hoping to come up with some workflow to keep blogs under version control and publish them when I’m done. Here’s the request I made to try to create a post:

curl -v 'https://fediverse.blog/api/v1/posts' -X POST -H "Authorization: Bearer $PLUME_TOKEN" -d $'{"title": "a","subtitle": "test","source": "content", "creation_date": "2022-11-04"}'

Unfortunately this always resulted in an HTTP 429 Unprocessable Entity status code. I’ve asked about it in the Matrix chat. If I can’t get a response from there I’ll make an issue and hopefully get some help from the maintainers.

Wrapping up

Overall, I like the platform. It’s the good kind of simple and I may also be interested in making some contributions as well. I’m excited to see what else I can do in the fediverse.