Galène videoconferencing server discussion list archives
 help / color / mirror / Atom feed
* [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