A grain of REST-y inspiration might be usefull

[JulienPalard]

Bonjour,

I know I'm not in the right repo but I was unable to find the repo of the API server code, don't hesitate to move the issue appropriately, sorry for this.

I know you're not advertising this API as being "RESTFULL", an as it's not, thanks for this, you did not fall into the typical buzzword stuffing game, and as a user I appreciated it.

I'm not trying to convince your that you should go full REST full HATEOAS and so on (maybe you should, but that's for another issue), I'll just try to convince you that a small grain of hateoas-inspired things could greatly enhance user-friendlytude.

So I'm trying the API for the first time, hitting /v5/users/me/organizations, got:

[
    {
        "logo": "https://cdn.helloasso.com/img/logos/afpy-7d88e49af32049488cceefe884fd5eeb.png",
        "name": "Afpy",
        "role": "OrganizationAdmin",
        "city": "Lyon",
        "zipCode": "69007",
        "description": "L'Association Francophone Python \u00e0 pour but de vulgariser et de diffuser aupr\u00e8s d\u2019un public francophone le langage de programmation Python, son \u00e9cosyst\u00e8me et ses applications.",
        "url": "https://www.helloasso.com/associations/afpy",
        "organizationSlug": "afpy"
    }
]

and to my great surprise there's no "self" URL (or whatever you want to call it), I'd expected something like:

"self": "https://api.helloasso.com/v5/organizations/afpy"

but more importantly there's no other link, so I have to manually browse the documentation while manually forging URLs in the code like:

for org in api.call("/v5/users/me/organizations"):
    items = api.call(f"/v5/organizations/{org['organizationSlug']}/items")

instead of:

for org in api.call("/v5/users/me/organizations"):
    items = api.call(org['items']))

(Yeah I'm a fan of the 2nd one.)

Another example, as the result of items I get:

    "pagination": {
        "pageSize": 20,
        "totalCount": 2674,
        "pageIndex": 1,
        "totalPages": 134,
        "continuationToken": "[redacted just in case]"
    }

forcing me to do:

for org in api.call("/v5/users/me/organizations"):
    items = api.call(f"/v5/organizations/{org['organizationSlug']}/items")
    while True:
        items = api.call(f"/v5/organizations/{org['organizationSlug']}/items?pageIndex={items['pagination']['pageIndex'] + 1}")

instead of:

for org in api.call("/v5/users/me/organizations"):
    items = api.call(org["items"])
    while True:
        items = api.call(items["next"])

(I definitely should not do a while True here, that's just to illustrate with a short code).

Bonus, if I had a next link, you could change the algorithm behind it server-side (like change from ?pageIndex=2 to ?from=2023-02-01T00:44:12 or to a cursor-based pagination without having all your clients to update their code, they just blindly follow the next link).

Just tell me what you think about it.

Bonne journée !