From: "Gabriel Kerneis" <gabriel@kerneis.info>
To: galene@lists.galene.org
Subject: [Galene] Re: API documentation
Date: Wed, 10 Apr 2024 22:47:36 +0200 [thread overview]
Message-ID: <32abf60e-fc7c-45cc-81d4-2c08feb16a04@app.fastmail.com> (raw)
In-Reply-To: <877ch5uhul.wl-jch@irif.fr>
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
next prev parent reply other threads:[~2024-04-10 20:47 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-10 19:40 [Galene] " Juliusz Chroboczek
2024-04-10 20:47 ` Gabriel Kerneis [this message]
2024-04-10 23:09 ` [Galene] " 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://lists.galene.org/postorius/lists/galene.lists.galene.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=32abf60e-fc7c-45cc-81d4-2c08feb16a04@app.fastmail.com \
--to=gabriel@kerneis.info \
--cc=galene@lists.galene.org \
--subject='[Galene] Re: API documentation' \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox