* [Galene] API documentation
@ 2024-04-10 19:40 Juliusz Chroboczek
2024-04-10 20:47 ` [Galene] " Gabriel Kerneis
0 siblings, 1 reply; 5+ messages in thread
From: Juliusz Chroboczek @ 2024-04-10 19:40 UTC (permalink / raw)
To: galene
https://galene.org/README.API.html
Please review.
-- Juliusz
^ permalink raw reply [flat|nested] 5+ messages in thread
* [Galene] Re: API documentation
2024-04-10 19:40 [Galene] API documentation Juliusz Chroboczek
@ 2024-04-10 20:47 ` Gabriel Kerneis
2024-04-10 23:09 ` Juliusz Chroboczek
` (2 more replies)
0 siblings, 3 replies; 5+ messages in thread
From: Gabriel Kerneis @ 2024-04-10 20:47 UTC (permalink / raw)
To: galene
I liked the fact that you explained in a recent email the purpose of ETag, by giving an example of a failing PUT due to concurrent updates. I think you should keep this in the API documentation.
The /0/ is intriguing, but maybe just because I'm not used to REST API design. I'd add a sentence explaining its versioning purpose anyway.
I would format groupname and username (and other API parameters) in italics to have them stand out, eg. in `/galene-api/0/.groups/groupname/.users/username`.
Explain the format of the stats endpoint. Idem for group and user definition (is it json, is it compatible with on-disk format, etc.). Maybe also specify the Content-Type for each endpoint?
Passwords: what do you mean exactly by "full password definition"? If this refers to the on-disk format, again, I think you should explicitly cross-reference it.
--
Gabriel
On Wed, 10 Apr 2024, at 21:40, Juliusz Chroboczek wrote:
> https://galene.org/README.API.html
>
> Please review.
>
> -- Juliusz
> _______________________________________________
> Galene mailing list -- galene@lists.galene.org
> To unsubscribe send an email to galene-leave@lists.galene.org
^ permalink raw reply [flat|nested] 5+ messages in thread
* [Galene] Re: API documentation
2024-04-10 20:47 ` [Galene] " Gabriel Kerneis
@ 2024-04-10 23:09 ` Juliusz Chroboczek
2024-04-11 0:02 ` [Galene] API versioning (was Re: Re: API documentation) Dianne Skoll
[not found] ` <171279372600.1000.262671797887854827@gauss.local>
2 siblings, 0 replies; 5+ messages in thread
From: Juliusz Chroboczek @ 2024-04-10 23:09 UTC (permalink / raw)
To: Gabriel Kerneis; +Cc: galene
Hi Gabriel!
> I think you should keep [the ETag explanation] in the API documentation.
Done.
> I would format groupname and username (and other API parameters) in
> italics to have them stand out, eg. in
> `/galene-api/0/.groups/groupname/.users/username`.
I'm not sure how to do that in a Markdown code block.
> Explain the format of the stats endpoint.
Clarified that the format is undocumented, and might change between
versions. (If you're curious, see static/stats.js, but don't rely on it.)
> Idem for group and user definition (is it json, is it compatible with
> on-disk format, etc.). Maybe also specify the Content-Type for each
> endpoint?
Done and done, thanks.
> Passwords: what do you mean exactly by "full password definition"? If
> this refers to the on-disk format, again, I think you should explicitly
> cross-reference it.
Done.
Thanks again,
-- Juliusz
^ permalink raw reply [flat|nested] 5+ messages in thread
* [Galene] API versioning (was Re: Re: API documentation)
2024-04-10 20:47 ` [Galene] " Gabriel Kerneis
2024-04-10 23:09 ` Juliusz Chroboczek
@ 2024-04-11 0:02 ` Dianne Skoll
[not found] ` <171279372600.1000.262671797887854827@gauss.local>
2 siblings, 0 replies; 5+ messages in thread
From: Dianne Skoll @ 2024-04-11 0:02 UTC (permalink / raw)
To: galene
On Wed, 10 Apr 2024 22:47:36 +0200
"Gabriel Kerneis" <gabriel@kerneis.info> wrote:
> The /0/ is intriguing, but maybe just because I'm not used to REST
> API design. I'd add a sentence explaining its versioning purpose
> anyway.
It was I who suggested a versioned API. My thinking was that if there's
some drastic change to the API, the version number could be incremented,
but (where feasible) the old API could still be supported so older API
clients would still work.
It may turn out to be completely unnecessary. But still, the cost of doing
it and not needing it is small, whereas the cost of not doing it and
then discovering it is needed is large.
Regards,
Dianne.
^ permalink raw reply [flat|nested] 5+ messages in thread
[parent not found: <171279372600.1000.262671797887854827@gauss.local>]
* [Galene] Re: API versioning (was Re: Re: API documentation)
[not found] ` <171279372600.1000.262671797887854827@gauss.local>
@ 2024-04-11 12:55 ` Juliusz Chroboczek
0 siblings, 0 replies; 5+ messages in thread
From: Juliusz Chroboczek @ 2024-04-11 12:55 UTC (permalink / raw)
To: Dianne Skoll; +Cc: galene
>> The /0/ is intriguing,
> It was I who suggested a versioned API.
Yep, credit where credit's due.
> the cost of doing it and not needing it is small, whereas the cost of
> not doing it and then discovering it is needed is large.
To be fair, even if we don't version the API at the outset, we could
always switch to /galene-api-v42/.groups/ or to /galene-api/.groups-v42/.
But, as you say, the cost is just two bytes per request.
-- Juliusz
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-04-11 12:55 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-04-10 19:40 [Galene] API documentation Juliusz Chroboczek
2024-04-10 20:47 ` [Galene] " Gabriel Kerneis
2024-04-10 23:09 ` Juliusz Chroboczek
2024-04-11 0:02 ` [Galene] API versioning (was Re: Re: API documentation) Dianne Skoll
[not found] ` <171279372600.1000.262671797887854827@gauss.local>
2024-04-11 12:55 ` [Galene] " Juliusz Chroboczek
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox