The path to Funkwhale 2.0: a new API

If you've been following this project for a while, you've probably heard the term "Funkwhale 2.0" a couple of times. It's something we've talked about many times, and something which acts as the ultimate near(ish)-term development goal for the project. However, despite talking about it, you've probably noticed that it's not here yet.

In this series, I'm going to give you an overview of what Funkwhale 2.0 actually is, what we need to do to get there, and what you can do to help (if you're willing and able!).

So, without further ado, let's dive into the first topic: the new API 🐳

What does 2.0 even mean?

The first question you probably have is: what exactly does 2.0 mean? We've had a lot more versions of Funkwhale than 2 already, haven't we?

The answer to this is: yes. However, Funkwhale follows something called Semantic versioning. Semantic versioning is a method for numbering software release versions that enables developers to communicate what type of change can be expected.

Semantic versioning uses the following structure:

  • Major version: a version change that brings breaking changes to behavior and/or the API layer
  • Minor version: a version change that brings new features or substantial changes without breaking existing behavior
  • Patch version: a small change that brings bug fixes and/or dependency updates

Funkwhale follows a six-monthly cadence of minor releases, meaning we ship a new version of the software containing new features approximately every six months. In between these releases, we ship multiple patch releases that fix bugs and update dependencies for security.

But what about major versions? Well, Funkwhale hasn't shipped one of those in a long time. The last major version release was Funkwhale 1.0 back in 2020. We decided to create version 1.0 when we were happy that the Funkwhale API was stable and would not be receiving any breaking changes. This is great for downstream developers as it means they can safely develop tools for and integrations with Funkwhale without worrying that we're going to change everything overnight.

So, what does 2.0 mean? It basically means that we plan to introduce a completely new API.

Why do we want to create a new API?

The Funkwhale API is the mechanism through which you communicate with the Funkwhale software. When you log in to the Funkwhale web app, upload content, and share libraries, the API takes in those instructions and performs the necessary actions.

The Funkwhale API has grown organically since the project first started eight years ago. Every time we needed a new feature or an improvement to an existing one, it was added to the API and shipped out. Once we were happy with how everything worked, we considered the API "stable" and created the first major version of Funkwhale: 1.0.

A lot has changed in those eight years and we've continued to add and add to the API to try and keep up. This has worked fine for the most part, but we've been dreaming up new functionality over the last couple of years and have come to the realization that we need the freedom to create something new and iterate on those ideas.

Creating a new API layer gives us the opportunity to step back and look at where Funkwhale is now, where we want it to be, and to plan a new API structure in a maintainable way. It also allows us to work on new things at our own pace, recreating existing functionality in a more efficient way, adding new features, and removing anything that we don't need any more.

The new API layer won't arrive all at once. We'll keep working on it in the background and update the web app to use new endpoints when we think they're ready. In fact, there's a good chance your server already supports Funkwhale API v2! We recently shipped our first endpoint, which is an updated and more efficient version of the Nodeinfo endpoint.

How does a new API affect you?

If you're not a developer, you might be asking why you should even care about a new API. How does this impact your day-to-day use of the software as a listener or content producer?

Every part of the Funkwhale app is powered by an API. This means that every action you take in the app from searching for content to favoriting tracks is done using the API. At the moment it's quite difficult for us to add new features, expand current features, and improve the platform's performance due to the structure of the v1 API. Creating a new API structure with a comprehensive specification, standard structure, and performance code will enable us to keep adding and improving Funkwhale's features.

Adding new features and improving performance is our main goal with API v2, so if you want a Funkwhale that's faster and can do more, you should look forward to it!

How you can help?

If you want to help us to build new features in Funkwhale here are a few ways you can help:


Running the Funkwhale project costs money. We have to pay for hosting, external audits, and paying a part-time maintainer to manage everything.

If you are willing and able to offer money to the project - either a one-time donation or a recurring donation - please check out our donation page. Any amount helps us enormously.

Talk about us

If you're excited about these changes, talking about them and spreading the word to your followers is a great way to help! The more people hear about the project and use it, the more support the project receives.

Contribute to the project

Designing and building a new web app is no small task, and the more people we can get involved the better. Specifically, you can help with the following:

  • Feeding back on specifications and features to let us know if anything could be improved
  • Testing new endpoints and features when they get implemented
  • Getting involved in the development process

If you have the time to spare and want to get involved, check out our contribution page for more information.

By @Sporiff in Community