388 lines
8.4 KiB
Markdown
388 lines
8.4 KiB
Markdown
# GoCarLog - API Spezifikation
|
|
|
|
Alle API-Endpunkte sind unter `/api/v1/...` erreichbar.
|
|
Antwortformat: JSON, Content-Type: `application/json`.
|
|
Fehlerantworten haben das Format: `{"error": "Fehlerbeschreibung", "code": 400}`.
|
|
|
|
---
|
|
|
|
## 1. Kraftstoffe abrufen
|
|
|
|
### `GET /api/v1/fuels`
|
|
|
|
Listet alle Kraftstoffe auf.
|
|
|
|
**Antwort (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{ "id": 0, "name": "Diesel", "unit": "L" },
|
|
{ "id": 1, "name": "Benzin", "unit": "L" },
|
|
{ "id": 2, "name": "LPG", "unit": "L" },
|
|
{ "id": 3, "name": "CNG", "unit": "L" },
|
|
{ "id": 4, "name": "Strom", "unit": "kWh" }
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Fahrzeug anlegen
|
|
|
|
### `POST /api/v1/vehicles`
|
|
|
|
Erstellt ein neues Fahrzeug.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"name": "Mein Auto",
|
|
"fuel_id": 0,
|
|
"manufacturer": "BMW",
|
|
"model": "320d",
|
|
"year": 2020,
|
|
"description": "Mein BMW 3er",
|
|
"license_plate": "AC B 1234",
|
|
"purchase_date": "2020-01-15",
|
|
"weight_kg": 1500,
|
|
"power_kw": 140,
|
|
"max_odometer": 300000
|
|
}
|
|
```
|
|
|
|
**Pflichtfelder:** `name`, `fuel_id`
|
|
|
|
**Antwort (201 Created):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"id": 1,
|
|
"name": "Mein Auto",
|
|
"manufacturer": "BMW",
|
|
"model": "320d",
|
|
"year": 2020,
|
|
"description": "Mein BMW 3er",
|
|
"license_plate": "AC B 1234",
|
|
"purchase_date": "2020-01-15",
|
|
"weight_kg": 1500,
|
|
"power_kw": 140,
|
|
"max_odometer": 300000,
|
|
"current_odometer": 0,
|
|
"fuel_id": 0,
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Fehler (400 Bad Request):**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "name und fuel_id sind erforderlich"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Fahrzeuge auflisten
|
|
|
|
### `GET /api/v1/vehicles`
|
|
|
|
Listet Fahrzeuge mit optionalen Filtern auf.
|
|
|
|
**Query-Parameter:**
|
|
|
|
| Parameter | Typ | Beschreibung |
|
|
|--------------|--------|--------------------------------------|
|
|
| `name` | string | Filter nach Name (Substring) |
|
|
| `license_plate` | string | Filter nach Kennzeichen |
|
|
| `fuel_id` | int | Filter nach Kraftstoff-ID |
|
|
| `manufacturer` | string | Filter nach Hersteller (Substring) |
|
|
| `model` | string | Filter nach Modell (Substring) |
|
|
| `year` | int | Filter nach Baujahr |
|
|
| `limit` | int | Maximale Anzahl Ergebnisse (default: 100) |
|
|
| `offset` | int | Offset für Pagination (default: 0) |
|
|
|
|
**Antwort (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "Mein Auto",
|
|
"manufacturer": "BMW",
|
|
"model": "320d",
|
|
"fuel_name": "Diesel",
|
|
"fuel_id": 0,
|
|
"power_kw": 140,
|
|
"current_odometer": 45230.5
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "Fahrrad",
|
|
"manufacturer": null,
|
|
"model": null,
|
|
"fuel_name": null,
|
|
"fuel_id": null,
|
|
"power_kw": null,
|
|
"current_odometer": 0
|
|
}
|
|
],
|
|
"total": 2
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Fahrzeugdetails
|
|
|
|
### `GET /api/v1/vehicles/:id`
|
|
|
|
Gibt alle Eigenschaften eines Fahrzeugs aus.
|
|
|
|
**Antwort (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"id": 1,
|
|
"name": "Mein Auto",
|
|
"manufacturer": "BMW",
|
|
"model": "320d",
|
|
"year": 2020,
|
|
"description": "Mein BMW 3er",
|
|
"license_plate": "AC B 1234",
|
|
"purchase_date": "2020-01-15",
|
|
"weight_kg": 1500,
|
|
"power_kw": 140,
|
|
"max_odometer": 300000,
|
|
"current_odometer": 45230.5,
|
|
"fuel": {
|
|
"id": 0,
|
|
"name": "Diesel",
|
|
"unit": "L"
|
|
},
|
|
"created_at": "2026-06-06T10:00:00Z",
|
|
"updated_at": "2026-06-06T10:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Fehler (404 Not Found):**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Fahrzeug nicht gefunden"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Logbucheintrag anlegen
|
|
|
|
### `POST /api/v1/logs`
|
|
|
|
Erstellt einen neuen Logbucheintrag. Aktualisiert automatisch `current_odometer` im Fahrzeug falls der Kilometerstand höher ist.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"vehicle_id": 1,
|
|
"log_type": "tankung",
|
|
"odometer": 46000,
|
|
"datetime": "2026-06-06T14:30:00Z",
|
|
"fuel_id": 0,
|
|
"cost": 65.50,
|
|
"quantity": 5.2,
|
|
"note": "Volle Tankung an Shell Station"
|
|
}
|
|
```
|
|
|
|
**Pflichtfelder:** `vehicle_id`, `log_type`, `odometer`
|
|
|
|
**Standardwerte:**
|
|
- `datetime` → aktuelle Zeit (wenn nicht angegeben)
|
|
- `cost` → 0
|
|
- `quantity` → 0
|
|
- `note` → "" (leer)
|
|
|
|
**log_type Werte:** `tankung`, `wartung`, `reparatur`, `notiz`
|
|
|
|
**Antwort (201 Created):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"id": 1,
|
|
"vehicle_id": 1,
|
|
"log_type": "tankung",
|
|
"odometer": 46000,
|
|
"datetime": "2026-06-06T14:30:00Z",
|
|
"fuel_id": 0,
|
|
"cost": 65.50,
|
|
"quantity": 5.2,
|
|
"unit": "L",
|
|
"note": "Volle Tankung an Shell Station",
|
|
"created_at": "2026-06-06T14:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Auto-Update Fahrzeug Odometer:**
|
|
Wenn `odometer > current_odometer` des Fahrzeugs, wird `current_odometer` automatisch aktualisiert.
|
|
|
|
**Fehler (400 Bad Request):**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "vehicle_id und log_type sind erforderlich"
|
|
}
|
|
```
|
|
|
|
**Fehler (404 Not Found):**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Fahrzeug nicht gefunden"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Logbucheinträge auflisten
|
|
|
|
### `GET /api/v1/logs`
|
|
|
|
Listet Logbucheinträge mit Filtern auf.
|
|
|
|
**Query-Parameter:**
|
|
|
|
| Parameter | Typ | Beschreibung |
|
|
|------------|--------|-----------------------------------|
|
|
| `vehicle_id` | int | Filter nach Fahrzeug-ID |
|
|
| `log_type` | string | Filter nach Eintragsart |
|
|
| `date_from` | string | Startdatum (ISO 8601) |
|
|
| `date_to` | string | Enddatum (ISO 8601) |
|
|
| `limit` | int | Maximale Anzahl (default: 100) |
|
|
| `offset` | int | Offset für Pagination (default: 0) |
|
|
|
|
**Antwort (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"vehicle_id": 1,
|
|
"vehicle_name": "Mein Auto",
|
|
"log_type": "tankung",
|
|
"odometer": 46000,
|
|
"datetime": "2026-06-06T14:30:00Z",
|
|
"fuel": {
|
|
"id": 0,
|
|
"name": "Diesel",
|
|
"unit": "L"
|
|
},
|
|
"cost": 65.50,
|
|
"quantity": 5.2,
|
|
"unit": "L",
|
|
"consumption_per_100km": "1.42 L/100km",
|
|
"note": "Volle Tankung an Shell Station",
|
|
"created_at": "2026-06-06T14:30:00Z"
|
|
}
|
|
],
|
|
"summary": {
|
|
"total_count": 1,
|
|
"cost_by_type": {
|
|
"tankung": 65.50,
|
|
"wartung": 0,
|
|
"reparatur": 0,
|
|
"notiz": 0
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Berechneter Verbrauch (`consumption_per_100km`):**
|
|
- Wird nur für Einträge mit `log_type: "tankung"` berechnet
|
|
- Verbrauch = `quantity / (current_odometer - previous_odometer) * 100`
|
|
- `previous_odometer` = Odometer des vorherigen Logeintrags (nach datetime sortiert, gleiches Fahrzeug)
|
|
- Wenn kein vorheriger Odometer-Wert existiert: Feld wird nicht ausgeliefert (`null`)
|
|
- Nicht-Tankungen (Wartung, Reparatur, Notiz) haben diesen Wert nicht
|
|
|
|
---
|
|
|
|
## 7. Durchschnittsverbrauch berechnen
|
|
|
|
### `GET /api/v1/vehicles/:id/consumption`
|
|
|
|
Berechnet den Durchschnittsverbrauch basierend auf Tankungseinträgen.
|
|
|
|
**Query-Parameter:**
|
|
|
|
| Parameter | Typ | Beschreibung |
|
|
|-----------|--------|-----------------------------------|
|
|
| `date_from` | string | Startdatum (ISO 8601, optional) |
|
|
| `date_to` | string | Enddatum (ISO 8601, optional) |
|
|
|
|
**Antwort (200 OK):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"vehicle_id": 1,
|
|
"vehicle_name": "Mein Auto",
|
|
"fuel_name": "Diesel",
|
|
"fuel_unit": "L",
|
|
"total_fuel": 156.8,
|
|
"total_distance": 12340.5,
|
|
"average_consumption": 6.37,
|
|
"consumption_unit": "L/100km",
|
|
"period": {
|
|
"from": "2026-01-01T00:00:00Z",
|
|
"to": "2026-06-06T23:59:59Z"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Berechnung:**
|
|
- `total_distance` = Summe der Distanzen zwischen aufeinanderfolgenden Tankungen (Differenz der Odometer-Stände)
|
|
- `total_fuel` = Summe der getankten Mengen (quantity)
|
|
- `average_consumption` = `total_fuel / total_distance * 100` (L/100km)
|
|
- Wenn keine ausreichenden Daten vorhanden: `average_consumption: null`
|
|
|
|
**Fehler (404 Not Found):**
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Fahrzeug nicht gefunden"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Fehler-Handling
|
|
|
|
Alle Fehlerantworten folgen diesem Muster:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Menschliche Fehlerbeschreibung",
|
|
"code": 400
|
|
}
|
|
```
|
|
|
|
| HTTP Status | Bedeutung |
|
|
|-------------|------------------------------|
|
|
| 200 | Erfolg |
|
|
| 201 | Erstellt (POST erfolgreich) |
|
|
| 400 | Ungültige Eingabe |
|
|
| 404 | Ressource nicht gefunden |
|
|
| 500 | Interner Serverfehler |
|