8.4 KiB
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):
{
"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:
{
"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):
{
"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):
{
"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):
{
"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):
{
"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):
{
"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:
{
"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→ 0quantity→ 0note→ "" (leer)
log_type Werte: tankung, wartung, reparatur, notiz
Antwort (201 Created):
{
"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):
{
"success": false,
"error": "vehicle_id und log_type sind erforderlich"
}
Fehler (404 Not Found):
{
"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):
{
"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):
{
"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):
{
"success": false,
"error": "Fahrzeug nicht gefunden"
}
Fehler-Handling
Alle Fehlerantworten folgen diesem Muster:
{
"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 |