* [Galene] Galene API frozen?
@ 2024-05-02 17:32 Juliusz Chroboczek
2024-05-02 19:22 ` [Galene] " Dianne Skoll
[not found] ` <171467774184.1473.5473206404325247014@gauss.local>
0 siblings, 2 replies; 7+ messages in thread
From: Juliusz Chroboczek @ 2024-05-02 17:32 UTC (permalink / raw)
To: galene
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* [Galene] Re: Galene API frozen?
2024-05-02 17:32 [Galene] Galene API frozen? Juliusz Chroboczek
@ 2024-05-02 19:22 ` Dianne Skoll
[not found] ` <171467774184.1473.5473206404325247014@gauss.local>
1 sibling, 0 replies; 7+ messages in thread
From: Dianne Skoll @ 2024-05-02 19:22 UTC (permalink / raw)
To: galene
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* [Galene] Re: Galene API frozen?
[not found] ` <171467774184.1473.5473206404325247014@gauss.local>
@ 2024-05-02 20:07 ` Juliusz Chroboczek
2024-05-02 20:17 ` Dianne Skoll
[not found] ` <171468106125.1473.12323438012415538261@gauss.local>
2024-05-03 18:26 ` Juliusz Chroboczek
1 sibling, 2 replies; 7+ messages in thread
From: Juliusz Chroboczek @ 2024-05-02 20:07 UTC (permalink / raw)
To: Dianne Skoll; +Cc: galene
> 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* [Galene] Re: Galene API frozen?
2024-05-02 20:07 ` Juliusz Chroboczek
@ 2024-05-02 20:17 ` Dianne Skoll
[not found] ` <171468106125.1473.12323438012415538261@gauss.local>
1 sibling, 0 replies; 7+ messages in thread
From: Dianne Skoll @ 2024-05-02 20:17 UTC (permalink / raw)
To: galene; +Cc: Juliusz Chroboczek
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* [Galene] Re: Galene API frozen?
[not found] ` <171468106125.1473.12323438012415538261@gauss.local>
@ 2024-05-02 20:33 ` Juliusz Chroboczek
2024-05-02 20:53 ` Dianne Skoll
0 siblings, 1 reply; 7+ messages in thread
From: Juliusz Chroboczek @ 2024-05-02 20:33 UTC (permalink / raw)
To: Dianne Skoll; +Cc: galene
>>> 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* [Galene] Re: Galene API frozen?
2024-05-02 20:33 ` Juliusz Chroboczek
@ 2024-05-02 20:53 ` Dianne Skoll
0 siblings, 0 replies; 7+ messages in thread
From: Dianne Skoll @ 2024-05-02 20:53 UTC (permalink / raw)
To: galene; +Cc: Juliusz Chroboczek
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* [Galene] Re: Galene API frozen?
[not found] ` <171467774184.1473.5473206404325247014@gauss.local>
2024-05-02 20:07 ` Juliusz Chroboczek
@ 2024-05-03 18:26 ` Juliusz Chroboczek
1 sibling, 0 replies; 7+ messages in thread
From: Juliusz Chroboczek @ 2024-05-03 18:26 UTC (permalink / raw)
To: Dianne Skoll; +Cc: galene
> 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.
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2024-05-03 18:26 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-05-02 17:32 [Galene] Galene API frozen? Juliusz Chroboczek
2024-05-02 19:22 ` [Galene] " Dianne Skoll
[not found] ` <171467774184.1473.5473206404325247014@gauss.local>
2024-05-02 20:07 ` Juliusz Chroboczek
2024-05-02 20:17 ` Dianne Skoll
[not found] ` <171468106125.1473.12323438012415538261@gauss.local>
2024-05-02 20:33 ` Juliusz Chroboczek
2024-05-02 20:53 ` Dianne Skoll
2024-05-03 18:26 ` Juliusz Chroboczek
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox