LRR for the future

[lxrst]

I've been using LANraragi for a few years now and have loved it.

I'm glad there's been so much activity in the community and project lately, but standardization of the LRR API could help it thrive long into the future.

I'd like to build an implementation of the LRR API in Rust, but I want to know that it won't change too much.
I'd also like to offer my time/labor if it would be of any help to the project.

[Difegue]

👋 This is a topic that comes up every now and then -- See #692.
Most of what I said there stands - Except the waste of time portion since you're mentioning making an alternate implementation instead of a second lightweight variant to bundle in the main server..

I keep API changes minimal since I don't want to throw external clients out the window on every new release - If you track the "API Changes" section on every release note you'll see it remains relatively stable. (I wouldn't be against eventually introducing versioning, but it'd have to be worth it imo)

I've floated the idea of writing an OpenAPI spec for the API in the past -- I'd switch the server to using that as a base instead of writing routes manually but I never got around to it. If you write said spec for your implementation I'll gladly integrate that 😛

[lxrst]

Yeah, I saw #692, but thought this was different enough to warrant its own discussion.

I like the idea of an OpenAPI spec. I'll implement the API as described in the docs, generate from that, and test against LRR.

[lxrst]

Ok, I think I may have a breaking change. The current LRR API has 3 different ways of specifying boolean values, each method used in separate parts of the codebase; none of which are JSON's way. This doesn't play nice with OpenAPI generators and looks ugly in all the web-based OpenAPI viewers (pardon the naming): rapidoc, redoc, swagger

I've verified this would affect Tachiyomi and Ichaival, but I can write patches for those two. I don't use any of the other projects that work with LRR, but can let them know it's coming.

I have a temporary fix (again pardon the naming), but I think it'd be worth it to break stuff now, while LRR isn't 1.0 software.

[Difegue]

wow my bools are not mentally deficient wtf....... (i'm not seeing the difference between n°1 and n°3 at a glance tho)

I use Mojo::JSON to render API responses out of Perl data structures, and Perl...does not actually have a dedicated boolean type.
In hindsight I shouldve used Mojo::JSON->true / Mojo::JSON->false, but I didn't know those existed and before long there were a bunch of API clients..

I never bothered with this too much since clients never complained 🤔
Would unifying all three kinds of bool under the non-string variant help? I don't personally mind making the switch to true/false but the API has existed for a number of years already and I wouldn't want to suddenly make everyone incompatible.

[lxrst]

i'm not seeing the difference between n°1 and n°3 at a glance tho

I forgot to change the doc comment 😞

Perl...does not actually have a dedicated boolean type

Sorry, genuinely didn't know that.

Would unifying all three kinds of bool under the non-string variant help?

Yes, that would be perfect.

As for the compatibility aspect, what if I keep the new flavor to the OpenAPI spec for now and submit patches to support both flavors? The old flavor could then be phased out after checking clients against the OpenAPI spec. Although, this strategy comes with the issue of more complicated deserialization routines client-side.

[lxrst]

Another issue: integer values in JSON strings; they aren't too much of a hassle, but it'd be more idiomatic to use JSON integers. I'm not sure if there's a reason this is done?

An example is /api/info:

"total_pages_read":"13",

[Difegue]

I forgot to change the doc comment 😞

Yeah, I realized after talking with API clients that isnew currently uses string true/false. Forgot about that one...

Integers in JSON strings as a whole are probably just type casting errors - I think it'd be possible to go in and fix those without breaking existing clients too hard. (I know LRReader would be fine, idk about others)

If you have a list of the endpoints which are affected by this, it probably wouldn't be too hard for me to go in and fix them all in a future release.

submit patches to support both flavors

I think this is the way to go, ideally API clients would want to support a range of server versions anyway, so if a version has a breaking change they'd have to keep the old code for a bit of time.

I guess we can go this way:

• Server-side, integer strings will be converted to JSON integers (that includes the stringified 0/1s in some API bools)
• Client-side, start supporting the OpenAPI spec which uses JSON true/false instead of 0/1
• Eventually, I'll switch the server to following the OpenAPI spec, fixing the remaining boolean issue