diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..43ba599 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,141 @@ +# API +Die API versucht möglichst RESTful zu sein. Es hat: +- Ressourcen im Plural +- Client-Server Trennung, Änderung der Daten auf der Oberfläche geschieht über `fetch()` an die API +- Einheitliche Schnittstelle + +Die Schnittstelle erfolgt vollständig über JSON. + +Es wurde auf Cache-fähigkeit verzichtet aus Zeitgründen. HATEOAS ist auch nicht vorhanden, da Zeitgründe und fragwürdig, ob es für ein Projekt diesen Umfang nötig ist. + +## API Pfade +IDs sind im UUID Format + +### Listen `/api/lists` + +| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg | +| ------------ | -------- | --------------------------------------------------- | ----------------------------------------- | ------------ | +| `/api/lists` | `GET` | Gibt alle vorhandenen Listen zurück mit Name und ID | / | 200 | +| | `POST` | Erlaubt es eine neue Liste zu erstellen | `listName` für den gewünschten Listenname | 201 | +#### `GET /api/lists` - Alle Listen +##### Body Beispiel +Leer +##### Response Beispiel +```json +[ + { + "listName": "Liste 1", + "listID": "ddb3ac36-8213-4f9d-bf1e-39c836768e57" + }, + { + "listName": "Liste 2", + "listID": "8937a2fa-2ab1-4b1e-8ee2-17bb0358dc1f" + }, + ... +] +``` +#### `POST /api/lists` - Erstellen einer Liste + +##### Body Beispiel +```json +{ + "listName": "Listenname" +} +``` +##### Response Beispiel +```json +{ + "listName": "Listenname", + "listID": "ddb3ac36-8213-4f9d-bf1e-39c836768e57" +} +``` +### Liste `/api/lists` + +| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg | +| ----------------- | -------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------ | +| `/api/lists/{id}` | GET | Gibt alle Gegenstände und Kategorien (mit ihren Gegenständen) in der Liste mit der UUID id zurück | `id`: UUID der Liste in der URL | 200 | +| | PATCH | Verändert den Namen der Liste | `id`: UUID der Liste in der URL. Im Body `listName` für den neuen Namen | 204 | +| | DELETE | löscht eine Liste | `id`: UUID Der Liste in der URL | 204 | +#### GET `/api/lists/{id}` - Inhalt der Liste +##### Body Beispiel +/ +##### Response Beispiel +```json +{ + "categories": [ + { + "categoryName": "testkategorie", + "items": [ + { + "status": false, + "itemName": "test", + "itemAmount": "1", + "itemID": "99403d02-4771-4a5a-b6a7-6f3af0a5ee84", + "categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4", + "listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137" + }, + { + "status": true, + "itemName": "test", + "itemAmount": "2", + "itemID": "fc2806f6-d430-49f8-8c56-a6e2bc9792a7", + "categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4", + "listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137" + } + ], + "categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4" + } + ], + "itemsNoCategory": [ //Gegenstände ohne Kategorie + { + "status": false, + "itemName": "test", + "itemAmount": "3", + "itemID": "38a0991e-4b51-42d7-b12c-0ddbcf6f583e", + "categoryID": null, + "listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137" + } + ] +} +``` +#### `PATCH /api/lists/{id}` - Bearbeiten der Liste +##### Body +```json +{ + "listName": "neuer Listname" +} +``` +##### Response +/ +#### `DELETE /api/lists/{id}` - Löschen einer Liste +##### Body +/ +##### Response +/ + + +### Kategorien `/api/categories` + + +| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg | +| ---------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------ | +| `/api/categories/{id}` | `GET` | Gibt den Inhalt der Kategorie zurück | / | 200 | +| | `POST` | Erlaubt es eine neue Kategorie zu erstellen | `categoryName` im Body für den gewünschten Kategorienamen | 201 | +| | `PATCH` | Ändern vom Namen der Liste | `categoryName` im Body für neuen Kategorienamen | 204 | +| | `DELETE` | Löschen einer Liste | `deleteAllItems=(true\|false)` als Queryparameter. Entscheidet, ob Gegenstände in der Kategorie mitgelöscht werden sollen | 204 | + + +#### `DELETE /api/categories/{id}?deleteAllItems=(true|false)` + +##### Body +/ +##### Response +/ + +### Gegenstände `/api/items` +| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg | +| ----------------- | -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ | +| `/api/items/{id}` | `GET` | Gibt den Inhalt des Gegenstands zurück | / | 200 | +| | `POST` | Erlaubt es einen neuen Gegenstand zu erstellen | `itemName,itemAmount,categoryID?,listID` im Body, für den Namen und Menge (entweder beide oder mindst einer muss vorhanden sein). | 201 | +| | `PATCH` | Ändern vom Namen, Menge oder Status eines Gegenstands | `itemName, itemAmount, isDone, categoryID` im Body. | 204 | +| | `DELETE` | Löschen eines Gegenstands | / | 204 |