Skip to content
Snippets Groups Projects

Add first post in path to Funkwhale 2.0

Merged Ciarán Ainsworth requested to merge funkwhale-2-api into main
1 file
+ 76
0
Compare changes
  • Side-by-side
  • Inline
+ 76
0
 
Title: The path to Funkwhale 2.0: a new API
 
Date: 2024-02-16
 
Authors: Sporiff
 
Category: Community
 
Slug: funkwhale-2-new-api
 
Summary: What is Funkwhale 2.0? What do we need to do to get there? This is the first post in a series that explains what we want Funkwhale to be and how we plan to get there.
 
 
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](https://semver.org/). 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:
 
 
### Donations
 
 
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](https://www.funkwhale.audio/donate/). 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](https://www.funkwhale.audio/contribute/) for more information.
 
 
[mjourdan]: https://dev.funkwhale.audio/mjourdan
Loading