[Galene] Galene API frozen?

[Galene] Galene API frozen?

[Juliusz Chroboczek]

Hi,

I think I'm done with the administrative API.

The API: https://galene.org/README.API.html

The JavaScript interface:
    https://github.com/jech/galene/blob/master/static/management.js

Example usage:
    https://github.com/jech/galene/blob/master/static/change-password.js

I've been testing the API by writing a mock management UI, you'll find it
in the branch "management-ui".  It's extremely primitive, just good enough
to veriy that the API is sufficient for everyday management purposes.

So unless something interesting comes up, I'm entering feature freeze for
Galene 0.9.

-- Juliusz

[Galene] Re: Galene API frozen?

[Dianne Skoll]

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

> The API: https://galene.org/README.API.html

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?

IMO, we should stick to JSON for request and result bodies.

Regards,

Dianne.

[Galene] Re: Galene API frozen?

[Juliusz Chroboczek]

> 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?
JSON cannot be streamed, at least not without some hacks, while a stream
of lines can easily be scanned in constant space.

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.

-- Juliusz

[Galene] Re: Galene API frozen?

[Dianne Skoll]

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.

[Galene] Re: Galene API frozen?

[Juliusz Chroboczek]

>>> 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.

I think there's a stronger argument.

Galene group names may contain any character including newlines.  So
I need to either forbid newlines in Galene group names, or define
a quoting mechanism.  And JSON comes bundled with its own quoting
mechanism...

I'll think it over.

> The usual way to handle this case is to provide a paged API

...and run into all sorts of issues with atomicity.

-- Juliusz

[Galene] Re: Galene API frozen?

[Dianne Skoll]

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

> I think there's a stronger argument.

> Galene group names may contain any character including newlines.  So
> I need to either forbid newlines in Galene group names, or define
> a quoting mechanism.  And JSON comes bundled with its own quoting
> mechanism...

Yup, there's that.  All the serialization/deserialization problems with
weird characters just go away.

> > The usual way to handle this case is to provide a paged API
> ...and run into all sorts of issues with atomicity.

Yes, but as I wrote earlier, I don't think it's needed for Galene.  I cannot
see any Galene installation becoming large enough that it would overburden
client code to handle the entire list of groups or users in memory.

Regards,

Dianne.

[Galene] Re: Galene API frozen?

[Juliusz Chroboczek]

> 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?

commit a12331ee09074a9e0a03f8c38ca0ad401c9ab10e
Author: Juliusz Chroboczek <jch@irif.fr>
Date:   Fri May 3 18:54:22 2024 +0200

    Use JSON arrays instead of plain text in API.
    
    Suggested by Dianne Skoll.