API Documentation

[fleaz]

• Find a good tool
• DO IT!

[flokli]

By now, there already is a swagger spec in the development branch.

I took a peek at it.

Some random thoughts (with adding some annotations about visibility/permissions) for regular users:

1. DELETE /users should be moved to DELETE /users/{userId}, while only allowing each user to delete its own account.
2. PUT /users -> PUT /users/{userId} (same reasons as 1.)
3. regarding /messages: Maybe types of sender, recipient and content would need to be redefined (pointing to user ids, so you can look those up via GET /users/{userId}, or embed via embed parameter, renaming content to data and setting type to json to support multiple fields?)
4. regarding #/components/schemas/Group: Why is owner not owners, and a list (with possibly more than one owner)?
5. I'd suggest stripping GET /groups/{groupId}/users, and instead let GET /groups/{groupId} return a members attribute with a list of user ids (also possible to embed)
6. The group joining and authorization flow is unclear to me, and violates Keep URLS Verb-Free, Avoid Actions — Think About Resources. Can users request access, or are they only invited to a group (which they can accept)? I'd suggest a /user/{userId}/invitations endpoint, with group owners being able to POST to random users /user/{userId}/invitations endpoint, and users being able to PATCH/PUT /groups/{groupId}/users, as soon as there exists an invitation (which will then be deleted as well)
7. The /groups/{groupId}/transactions/{transactionId} could be moved to /transactions/{transactionId}. (see Consider Using (Non-) Nested URLs)

[flokli]

/cc @megfault

[mschader]

About 1. and 2.
If only the user can access these API endpoints, wouldn't it be sufficient to call it /user and leave the id out of the request?
It would probably be confusing to have /users and /user, but this could be solved by changing one of the endpoints name in a more meaningful way.

[fleaz]

We should also try to get the API docs up to date to match the current level of the code and "freeze" it so we can finish version 1.0 of both backend and frontend?

[flokli]

I didn't look into how much code and spec diverged by now - my comment was from January ;-)

[fleaz]

API-Doku unter /docs auf aktuellen Stand bringen