[Galene] Re: Galene API frozen?

[Dianne Skoll <dianne@skoll.ca>]

On Thu, 02 May 2024 22:07:43 +0200
Juliusz Chroboczek <jch@irif.fr> wrote:

> > For the API endpoints:

> > GET /galene-api/0/.groups/
> > GET /galene-api/0/.groups/groupname/.users/

> > rather than returning plain-text, one-per-line, wouldn't it make
> > more sense to return a JSON array?

> No objection if people feel strongly that way, but what's the
> advantage?

Consistency.  If all the API endpoints return JSON, then the client code
can simply deserialize the JSON objects and not worry about having to
use different parsers for different endpoints.

> JSON cannot be streamed, at least not without some hacks,
> while a stream of lines can easily be scanned in constant space.

Do any Galene installations have enough users or groups that this will
be an issue?  I can't imagine it would matter unless you have several
thousand users.  The usual way to handle this case is to provide a
paged API where you can ask for users N through N+M (and the API
therefore needs to provide them in a consistent order), but IMO this
is not needed for Galene.

> If the goal is to make the format extensible, then we'll want to send
> either an array of dictionaries or a JSONL stream, but I really
> cannot see any advantage to switching to just an array of strings.

Extensibility is also a consideration, so an array of dictionaries might
be better, but consistency in serializing/deserializing the objects IMO
is a more important consideration.

Regards,

Dianne.