From 95b3e9b00d95113da8cfb90f56f74a45061bbade Mon Sep 17 00:00:00 2001 From: Elias Projahn Date: Wed, 13 May 2020 16:57:27 +0200 Subject: [PATCH] server: Add README.md with API documentation draft --- server/README.md | 207 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 server/README.md diff --git a/server/README.md b/server/README.md new file mode 100644 index 0000000..a55e0f0 --- /dev/null +++ b/server/README.md @@ -0,0 +1,207 @@ +# Musicus server + +A server hosting a shared Musicus database. + +## Introduction + +A Musicus server publishes the contents of a Musicus database via a simple +HTTP API. Registered users may additionally add entities to the database and +some users maintain the database by editing or deleting entities. + +## API documentation + +Important note: The Musicus API is not stable yet. This means, that there will +probably be breaking changes without any kind of versioning. At the moment, +this documentation while mostly describing the API as it works today is +nothing more than a draft. + +### Retrieving information + +All entities are available to the public without authentication. The response +will have the content type `application/json` and the body will contain either +a list of JSON objects or just a JSON object. The server handles `GET` requests +at the following routes: + +| Route | Result | Pagination | Search | +| ------------------------ | ----------------------------------------------- | ---------- | ------ | +| `/persons` | A list of persons | Yes | Yes | +| `/persons/{id}` | One person by its ID or error `404` | No | No | +| `/persons/{id}/works` | A list of works by the person or error `404` | Yes | Yes | +| `/instruments` | A list of instruments | Yes | Yes | +| `/instruments/{id}` | One instrument by its ID or error `404` | No | No | +| `/works/{id}` | One work by its ID or error `404` | No | No | +| `/works/{id}/recordings` | A list of recordings of the work or error `404` | Yes | No | +| `/ensembles` | A list of ensembles | Yes | Yes | +| `/ensembles/{id}` | One ensemble by its ID or error `404` | No | No | +| `/recordings/{id}` | One recording by its ID or error `404` | No | No | + +#### Pagination + +Routes that use pagination for their result will always limit the result to a +constant amount of entities. You can get other pages using the `?p={page}` +query parameter. + +#### Search + +Routes supporting search can be supplied with a search string using the +`?s={search}` query parameter. + +### Authentication + +Users that would like to contribute to the information hosted by the server +will need to authenticate. + +#### Registration + +For registration, the server handles `POST` requests to `/account/register`. +The request body has to be valid JSON and have the following form. + +```json +{ + "username": "username", + "email": "optional@email.address", + "password": "password" +} +``` + +The following errors may occur: + +| Error code | Explanation | +| ---------- | ---------------------------------------- | +| `400` | The body was malformed. | +| `409` | The username is already taken. | +| `415` | Content type was not `application/json`. | + +#### Login + +All protected resources will check for a valid token within the authorization +header of the request. The client can get a token by sending a `POST` request +to `/account/login`. The request body should contain a valid JSON object of the +following form: + +```json +{ + "username": "username", + "password": "password" +} +``` + +If the operation was successful, the token will be returned in the response +body as a single string with the content type `text/plain`. + +The following errors may occur: + +| Error code | Explanation | +| ---------- | ---------------------------------------- | +| `400` | The body was malformed. | +| `401` | Login failed | +| `415` | Content type was not `application/json`. | + +#### Authorization + +When accessing a protected resource, the client should include a authorization +header with the token retrieved when logging in. The authorization type should +be `Bearer`. If the provided token is valid and the user is authorized to +perform the requested action, the expected response for the route beeing +accessed will be returned. + +The following errors may occur: + +| Error code | Explanation | +| ---------- | -------------------------------------------------------- | +| `400` | The authorization header was malformed. | +| `401` | The provided token is invalid. | +| `403` | The user is not allowed to perform the requested action. | + +#### Retrieving account details + +The client can retrieve the current account details for a user using a `GET` +request to `/account/details`. The user has to be logged in. The returned body +will have the content type `application/json` and the following format: + +```json +{ + "email": "optional@email.address" +} +``` + +#### Changing account details + +To change the email address or password for an existing user, the client may +send a `POST` request to `/account/details`. The content type has to be +`application/json` and the body should contain a valid JSON object in the +following form: + +```json +{ + "username": "username", + "password": "old password", + "newEmail": "optional@email.address", + "newPassword": "new password" +} +``` + +The `newEmail` and `newPassword` parameters both can be left out or set to null +to indicate that they remain unchanged. `username` and `password` have to be +provided. If the user doesn't exist or the old password was wrong, an error +`403` will be returned. + +#### Deleting an account + +To delete an existing account, the client may send a `POST` request to +`/account/delete`. The content type has to be `application/json` and the body +should contain a valid JSON object in the following form: + +```json +{ + "username": "username", + "password": "password" +} +``` + +If the user doesn't exist or the password was wrong, an error `403` will be +returned. + +### Adding new entities + +To be able to add new entities, the user has to be authenticated and authorized +to do so. By default, this is the case for newly registered users. The content +type should be `application/json` and the body should contain a valid JSON +object matching the specific resource. The entity ID should be generated on +the client side to facilitate offline usage. This means, that entity creation +will be handled using `PUT` requests to the following routes: + +- `/persons/{id}` +- `/instruments/{id}` +- `/works/{id}` +- `/ensembles/{id}` +- `/recordings/{id}` + +The following errors may occur: + +| Error code | Explanation | +| ---------- | ---------------------------------------- | +| `400` | The body was malformed. | +| `415` | Content type was not `application/json`. | + + +### Editing existing entities + +To be able to edit existing entities, the user has to be authenticated and +authorized to do so. By default, newly registered users are not allowed to edit +entities. The interface is exactly the same as the one for adding new entities. + +### Deleting entities + +To be able to delete existing entities, the user has to be authenticated and +authorized to do so. By default, newly registered users are not allowed to +delete entities. The following routes handle `DELETE` requests for deleting +entities: + +- `/persons/{id}` +- `/instruments/{id}` +- `/works/{id}` +- `/ensembles/{id}` +- `/recordings/{id}` + +If the entity doesn't exist, an error `404` will be returned. \ No newline at end of file