Welcome to the NZRT Wiki Podcast. Today we’re looking at REST API Overview.

So let’s talk about how Flarum’s API works and how you can interact with it. The first thing to know is that Flarum follows something called the JSON API specification. What that means for you in practice is that every request you send and every response you get back uses a standard content type called application JSON. The base URL you’ll be hitting for everything is your forum domain, followed by slash api.

Let’s start with authentication, because you need to get this right before anything else works. The recommended approach for write operations is to get a session token. You do this by sending a POST request to the token endpoint, passing in a JSON body with your username under the identification field and your password. The API comes back with a response containing two things: a token, which is a long string of characters, and your user ID. From that point on, you include that token in the Authorization header of every request, formatted as the word Token followed by your token string.

Here’s an important warning that will save you a lot of headaches. If you’re using pre-generated API tokens from the user settings panel in Flarum, those work fine for read-only GET requests, but they will fail on POST, PATCH, and DELETE operations because of CSRF validation. So always go through the token endpoint for anything that writes data.

Now let’s walk through what you can actually do with the API. There are three main groups of endpoints. For discussions, you can list all discussions, fetch a single discussion by its ID, create a new discussion, update an existing one, or delete one. For posts, meaning individual replies within a discussion, you can list posts, create a new reply, edit an existing post, or delete one. And for users, you can list all users or fetch a single user by ID. There’s also an endpoint to list all available tags.

Next, let’s talk about how you structure a request body when you’re creating or updating something. The JSON API format wraps everything inside a top-level data object. Inside that, you specify the type, for example the word discussions, then an attributes section where you put things like the title and the body content of your post. If you need to attach a tag, you add a relationships section, and inside that a tags object, which holds a data array. Each item in that array is an object with a type of tags and the numeric ID of the tag you want to apply.

For filtering and pagination, you append query parameters to your URL. To filter discussions by a tag, you use filter with tag as the key and the tag slug as the value. To control how many results come back, you use page limit and set a number. To offset into the results for pagination, you use page offset. You can also do text search across discussions or users by using filter with q as the key and your search term as the value.

Finally, a word on patching tags onto an existing discussion. The structure is similar to creation. You send a PATCH request with a data object specifying the type as discussions, the ID of the discussion you’re targeting, and then a relationships block with the tag you want to apply. One critical thing to be aware of here: you can only send one tag per PATCH request. If you try to send multiple tags in a single request, the API will return a 500 error. So if you need to apply multiple tags, make separate requests.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.