Initial commit: gocarlog project — Milestones 1-10 completed
This commit is contained in:
@@ -0,0 +1,387 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user