API fork
As it was discussed in the IRC, we most likely want to fork MastoAPI into our own.
Reasons:
- We would gain control over our own API and can change it the way we want, not just follow whatever Mastodon is doing.
- Adding more extensions will be much easier, since we won't claim compatibility with clients not explicitly supporting Pleroma
- We will still support vanilla MastoAPI (+ extensions) for mastodon and legacy clients
- Maintaining compatibility with older/newer versions of clients/FEs will be easier since we would be able to version our API
How to do it (proposal):
Currently we have /api/v1/
and /api/v2/
, as well as /api/pleroma/
. We should either make /api/pleroma/v1
or start using version-requesting headers - see https://restfulapi.net/versioning/ . All mastoapi and pleroma endpoints should be copied there, like so:
-
/api/v1/search
->/api/pleroma/v1/search
-
/api/v2/search
->/api/pleroma/v1/search-v2
- all v2 or newer endpoints should have a suffix instead of becoming v2 - remember, it is our version. -
/api/pleroma/frontend_configurations
->/api/pleroma/v1/frontend_configurations
-
/api/v1/streaming
->/api/pleroma/v1/streaming
The point is - all existing API should remain more-or-less untouched. Adding new features or breaking behavior means we need to create v2 endpoint.
We don't have create /pleroma/v1
immediately but instead create it when we want to make some change into existing API, i.e. consider existing API a "v0"
It doesn't necessary have to be /pleroma/v1
, we can use /pleroma-v1
, /pv1
or anything else. To avoid confusion we should settle on one versioning method only, i.e. not mixing prefixing /vN
and accept-version: 1
header or such.
Examples of application and profits:
Say we want to add Deletes into non-streaming API so that clients not supporting websockets (mobile) and PleromaFE in poll mode (either disabled by user or recovering from WS connection failure) can still receive deletes.
we copy /api/v1/timelines/home
(and possibly others) into /api/pleroma/v1/timelines/home
:
- New clients can switch to use new API and support deletes that way.
- Old clients are unaffected
- We don't have to test each and every client software in existence to see if it breaks because of it.
- We don't have to devise a way to extend existing API to make it compatible with everything.
Additional thoughts
Supporting new API is cool, but it also means client software targeting it loses compatibility with older servers, and some developer would prefer to avoid that and would try to figure out if given server supports certain endpoints or not, we should provide an easy way of knowing which endpoints are available, i.e. additional field in /api/v1/instance
or similar.
Versioning entire API or just endpoints? Synchronize versions? Semver?
In general there doesn't seem to be much profit in versioning entire API - a lot of endpoints will be identical across versions anyway, versioning endpoints separately also doesn't always make sense since some endpoints are meant to be used together. I would suggest versioning endpoints separately but endpoints meant to be used together should all have matching versions, even if it means skipping a version (i.e. going v1 -> v3), it would sorta be a "version of a feature". I don't see much need for semver either since any number change already implies incompatibility, and i would just prefer using single number.