Unstable API path

[MrKaplan-lw]

API versions like v3 or v4 imply some degree of stability of the APIs.
Ideally, any changes to endpoints in a versioned API should be backwards compatible to earlier Lemmy versions with the same API version.

For new APIs, like #5669, I propose the option of having an "unstable" API path like /api/unstable/vote_analytics/given_by_person, which does not have any stability promises beyond being compatible with the corresponding Lemmy-UI version. This allows implementing new features without committing to API stability yet, as often it is needed for APIs to see real world usage before shortcomings are identified. Once the API has seen some real world usage and is determined to be viable for promotion to a stable version, it can be moved from unstable to v3/v4.

This shouldn't be a requirement for all new API implementations, it should be up to the implementer to determine whether the endpoint is considered stable enough.

This may also allow shipping new experimental functionality faster before being ready to commit to a stable API spec, possibly including multiple implementations that can be compared in production environments.

[christianjuth]

If this is implemented, lemmy-js-client should show what endpoints are unstable.

For this example, let's pretend there is an unstable migrate account endpoint.

Could be one of these:

• client.unstableMigrateAccount(form, fetchOptions)
• client.unstable.migrateAccount(form, fetchOptions)

[dessalines]

Both these are good ideas.

I could see this being especially useful for test-like functionality where we're not sure how it would work (or if its even desirable) in practice, and might need to tweak or substantially change it.

Having them under a different heading would also make it potentially easier to block in nginx if it ends up being subject to DDOS attacks or performance problems.

[Nutomic]

Makes sense. Besides the vote analytics are there any already merged features that should be marked as unstable?

[dessalines]

Not that I can think of.