Files

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 |