This commit is contained in:
Technoir committed 2026-10-19 11:19:00 +02:00
1 parent ad4a9d12d5
commit d5389af958
1 file changed
+141
+141
View File
@@ -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 |