[Galene] API documentation

[Galene] API documentation

[Juliusz Chroboczek]

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

Please review.

-- Juliusz

[Galene] Re: API documentation

[Gabriel Kerneis]

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

[Galene] Re: API documentation

[Juliusz Chroboczek]

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

[Galene] API versioning (was Re: Re: API documentation)

[Dianne Skoll]

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.

[Galene] Re: API versioning (was Re: Re: API documentation)

[Juliusz Chroboczek]

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