Files
gocarlog/docs/api-spec.md
T

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 → 0
  • quantity → 0
  • note → "" (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