# 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 |