Open issues on popular lemmy apps to prepare for `1.0.0` release

[dessalines]

Now that we've fundamentally changed nearly all the data structs, there's no reason to keep an api/v3 in the codebase. Nearly every data structure was changed with #5482 .

As one example:

GET /community/id=? now returns CommunityViews whose data structure is completely changed, regardless of the api structure. Clients thinking they can hit api/v3 and they will receive the same data structures as lemmy 0.19, will be wrong.

Apps should either use backwards-compatible API libraries like MV-GH's for kotlin, or pull down tagged libraries as git submodules (IE lemmy-js-client v0.19, v1.0, etc).

They can which decide which to use based on the lemmy version from GetSite or Nodeinfo.

[Nutomic]

Before doing this we need to be sure that all major Lemmy apps are updated to support the new API. Otherwise instances would stay on 0.19 for a long time to ensure that app users dont get problems. This was part of the reason why lemmy.world stayed on 0.19.3 for so long. In the worst case we may have to keep supporting 0.19 with new updates for a long time. So to avoid that we should make the transition to 1.0 as smooth as possible.

I suggest we follow these steps:

• Implement all remaining breaking changes
  • post_view cleanup
  • pagination cursors
  • remote site bans
• Publish 1.0.0-beta.0
• Put it on voyager.lemmy.ml and https://join-lemmy.org/api/main
• Open issues for all Lemmy apps to support new API version. These are the most popular apps based on number of requests to lemmy.ml
  • Mlmym
  • Jerboa
  • Sync
  • Mlem
  • Boost
• Only remove the old api once the new api is supported by most apps/frontends

[dessalines]

Agree, making issues on their repos is a great idea. We'll have to give a lot of time for app devs to prepare for 1.0.0 , as its a completely changed API.

I'll rename this issue to be about that.

[christianjuth]

• If this doesn't already exist, could we get a v1 API up soon to actually test against
• If I'm using lemmy-js-client, will it be possible for me to simultaneously support v1 and servers that haven't updated to v1 yet?

That second question might be obvious, but I'm relatively new to Lemmy and I've put very little though into updating my app to support v1. But I want to gauge how difficult it will be if only some servers are on v1.

[Nutomic]

You can browse the 1.0 api docs and test with voyager.lemmy.ml (note lemmy-ui is not updated yet, only the api works.

The js client main branch is currently only compatible with 1.0, it would require a wrapper which switches between 0.19 and 1.0 js client versions conditionally.

[christianjuth]

You can browse the 1.0 api docs and test with voyager.lemmy.ml (note lemmy-ui is not updated yet, only the api works.

The js client main branch is currently only compatible with 1.0, it would require a wrapper which switches between 0.19 and 1.0 js client versions conditionally.

Idk if I'm doing something wrong, but I can't get any of the servers listed in the V1 docs to work — I'm using the /v4/site endpoint to test. But I started laying the groundwork for V1 support and I think I can get pretty far just based off the TypeScript interfaces.

But stepping back for a second, is there somewhere that summarizes what V1 changes? Aside from internal refactoring, what will change externally? I noticed some fields have been renamed (love that things are more consistent now) and aggregates seem to be rolled into the objects they are attached to. But is thinking of V1 as mostly renaming and some slight reorganization of fields missing the bigger picture?

Edit: idk if you read this and fixed it, but the new API seems to be working now. I also found the blog post going over most of the changes. Thanks!

[Nutomic]

For reference the post is here: https://join-lemmy.org/news/2025-02-03_-_Breaking_Changes_in_Lemmy_1.0

Here are some more breaking changes I found now, we should probably add them to the blog post, or write a new post:

• https://github.com/LemmyNet/lemmy/pull/5478
• https://github.com/LemmyNet/lemmy/pull/5407
• https://github.com/LemmyNet/lemmy/pull/5403
• https://github.com/LemmyNet/lemmy/pull/5476
• https://github.com/LemmyNet/lemmy/pull/5463
• https://github.com/LemmyNet/lemmy/pull/5535
• https://github.com/LemmyNet/lemmy/pull/5534
• https://github.com/LemmyNet/lemmy/pull/5515
• https://github.com/LemmyNet/lemmy/pull/5664

[christianjuth]

You can browse the 1.0 api docs and test with voyager.lemmy.ml (note lemmy-ui is not updated yet, only the api works.

The js client main branch is currently only compatible with 1.0, it would require a wrapper which switches between 0.19 and 1.0 js client versions conditionally.

1. Is it safe to assume that future versions of lemmy-js-client will only support a single major version of Lemmy? I already starting building the lemmy-js-client wrapper you suggested.
2. Is there a better way to detect what endpoints to hit than simultaneously hitting e.g. lemmy.ml/api/v3/site and lemmy.ml/api/v4/site to see which works? It feels really dumb to hit both of those every time my app starts, but I can't think of a better way if we assume any Lemmy server can update to v1 at any point (after v1 ships).

[Nutomic]

1. As youre already building that wrapper there is no need to duplicate the effort. Would be good if you could link your repo in the lemmy-js-client readme and the docs.
2. You can check /nodeinfo/2.1 to get the Lemmy version and some other details. Or call only /api/v4/site, and if that fails with 404 fallback to /api/v3/site

[christianjuth]

1. As youre already building that wrapper there is no need to duplicate the effort. Would be good if you could link your repo in the lemmy-js-client readme and the docs.
2. You can check /nodeinfo/2.1 to get the Lemmy version and some other details. Or call only /api/v4/site, and if that fails with 404 fallback to /api/v3/site

For now, I'm thinking this wrapper I wrote – I'm calling it an api adapter – will live within the same codebase as my app, but I'll do my best to write it in a way that other people can yank out a single folder and past the adapter into their app self contained.

Since this is an internal part of my app and I may move this folder around at any point, I'm thinking the best way to prevent broken GitHub links is to link to a wiki page on my project that I can update as needed. I created this page as a placeholder and wrote a very brief summary of how this adapter will work.

Note, I've written this adapter to fit the specific needs of my app, and likely others may need to modify it to suit their needs. That's why I'm thinking its more useful to have people copy it instead of me publishing it to npm. Let me know if you have any thoughts here and/or if you agree high level with how I described this adapter will work.

[dessalines]

You can import multiple versions of lemmy-js-client with package aliases: https://willmendesneto.com/posts/installing-multiple-versions-of-the-same-package-in-your-project-via-package-aliases/

[Nutomic]

There is now backwards compatibility for API v3 in Lemmy 1.0 which covers functionality for general browsing and commenting. However new features, mod/admin actions, user settings and notifications are only available through API v4 as there have been lots of changes. This means existing clients will continue working with Lemmy 1.0. Still they should upgrade to get access to new features.

https://github.com/LemmyNet/lemmy/pull/6120 https://github.com/LemmyNet/lemmy/pull/6135