docs(api): sync documentation from api@b02d62331ed4013d6fb72c2e5d6dc91302f5c589

Author: github-actions[bot]

docs/api/API_ERRORS.md

@@ -16,16 +16,16 @@ All errors follow [RFC 7807 Problem Details](./PROBLEM_DETAILS_RFC_7807.md).
 - Vehicle with specified make/model/year does not exist
 - Manufacturer slug is invalid or has no models
 
-**Resolution:** Verify the resource identifier. Use `/api/v1/makes` to list valid manufacturers or `/api/v1/vehicles` to browse available vehicles.
+**Resolution:** Verify the resource identifier. Use `/api/v1/makes/list` to list valid manufacturers or `/api/v1/vehicles/list` to browse available vehicles.
 
 **Example:**
 ```json
 {
   "type": "https://github.com/open-ev-data/open-ev-data-api/blob/main/docs/API_ERRORS.md#errorsnot-found",
   "title": "Resource Not Found",
   "status": 404,
-  "detail": "Vehicle not found: invalid/model/2024",
-  "instance": "/api/v1/vehicles/invalid/model/2024"
+  "detail": "Vehicle not found with code: invalid:model:2024:unknown",
+  "instance": "/api/v1/vehicles/code/invalid:model:2024:unknown"
 }
 ```
 
@@ -50,7 +50,7 @@ All errors follow [RFC 7807 Problem Details](./PROBLEM_DETAILS_RFC_7807.md).
   "title": "Invalid Request",
   "status": 400,
   "detail": "Search query must be at least 2 characters",
-  "instance": "/api/v1/search"
+  "instance": "/api/v1/vehicles/search"
 }
 ```
 
@@ -75,7 +75,7 @@ All errors follow [RFC 7807 Problem Details](./PROBLEM_DETAILS_RFC_7807.md).
   "title": "Internal Server Error",
   "status": 500,
   "detail": "Database query failed",
-  "instance": "/api/v1/vehicles"
+  "instance": "/api/v1/vehicles/list"
 }
 ```
 
@@ -111,10 +111,7 @@ All errors follow [RFC 7807 Problem Details](./PROBLEM_DETAILS_RFC_7807.md).
 | Endpoint | Possible Errors |
 |----------|-----------------|
 | `GET /health` | 500, 503 |
-| `GET /makes` | 500 |
-| `GET /makes/{make}/models` | 404, 500 |
-| `GET /vehicles` | 400, 500 |
-| `GET /vehicles/code/{unique_code}` | 404, 500 |
-| `GET /vehicles/{make}/{model}/{year}` | 404, 500 |
-| `GET /vehicles/{make}/{model}/{year}/variants` | 404, 500 |
-| `GET /search` | 400, 500 |
+| `GET /makes/list` | 500 |
+| `GET /vehicles/list` | 400, 500 |
+| `GET /vehicles/code/{code}` | 404, 500 |
+| `GET /vehicles/search` | 400, 500 |

docs/api/ARCHITECTURE.md

@@ -279,12 +279,12 @@ sequenceDiagram
 
     Deploy->>API: Deploy ev-server + vehicles.db
     API->>API: Load database into memory
-    Client->>API: GET /api/v1/vehicles?make=tesla
+    Client->>API: GET /api/v1/vehicles/list?make=tesla
     API->>API: Query local database
     API-->>Client: Return JSON response
 
-    Client->>API: GET /api/v1/vehicles/tesla/model_3/2024
-    API->>API: Query by composite key
+    Client->>API: GET /api/v1/vehicles/code/tesla:model_3:2024:model_3
+    API->>API: Query by unique code
     API-->>Client: Return vehicle details
 
 ```
@@ -607,7 +607,7 @@ Health check endpoint
 }
 ```
 
-#### GET `/api/v1/vehicles`
+#### GET `/api/v1/vehicles/list`
 List all vehicles with pagination and filtering
 
 **Query Parameters**:
@@ -633,48 +633,36 @@ List all vehicles with pagination and filtering
 }
 ```
 
-#### GET `/api/v1/vehicles/{make}/{model}/{year}`
-Get specific vehicle details
+#### GET `/api/v1/vehicles/code/{code}`
+Get specific vehicle by unique code
 
 **Path Parameters**:
-- `make`: Manufacturer slug
-- `model`: Model slug
-- `year`: Model year
+- `code`: Vehicle unique code (format: `make:model:year:filename`)
 
 **Response**: Full canonical vehicle object
 
-#### GET `/api/v1/vehicles/{make}/{model}/{year}/variants`
-List all variants for a specific vehicle
+#### GET `/api/v1/vehicles/search`
+Full-text search across vehicles
+
+**Query Parameters**:
+- `q`: Search query (minimum 2 characters)
+- `page`, `per_page`: Pagination
 
-**Response**: Array of variant vehicles
+**Response**: Ranked search results with pagination
 
-#### GET `/api/v1/makes`
-List all manufacturers
+#### GET `/api/v1/makes/list`
+List all manufacturers with model information
 
 **Response**:
 ```json
 {
   "makes": [
-    { "slug": "tesla", "name": "Tesla", "vehicle_count": 42 },
-    { "slug": "byd", "name": "BYD", "vehicle_count": 38 }
+    { "slug": "tesla", "name": "Tesla", "vehicle_count": 42, "models": ["Model 3", "Model S", "Model X", "Model Y"] },
+    { "slug": "byd", "name": "BYD", "vehicle_count": 38, "models": ["Dolphin", "Seal", "Atto 3"] }
   ]
 }
 ```
 
-#### GET `/api/v1/makes/{make}/models`
-List all models for a manufacturer
-
-**Response**: Array of models with vehicle counts
-
-#### GET `/api/v1/search`
-Full-text search across vehicles
-
-**Query Parameters**:
-- `q`: Search query
-- `page`, `per_page`: Pagination
-
-**Response**: Ranked search results
-
 ### 7.3. Configuration
 
 Configuration via environment variables:

docs/api/CRATE_EV_ETL.md

@@ -9,7 +9,7 @@ This crate provides a command-line tool for transforming layered JSON vehicle da
 ## Usage
 
 ```bash
-ev-etl --input ../open-ev-data-dataset/src --output ./output --formats json,sqlite
+cargo run -p ev-etl -- --input ../open-ev-data-dataset/src --output ./output --formats json,sqlite
 ```
 
 ## Output Formats

docs/api/CRATE_EV_SERVER.md

@@ -9,7 +9,7 @@ This crate provides a high-performance HTTP REST API server for querying electri
 ## Usage
 
 ```bash
-DATABASE_URL=vehicles.db ev-server
+DATABASE_URL=./output/vehicles.db cargo run -p ev-server
 ```
 
 ## Environment Variables
@@ -26,12 +26,10 @@ DATABASE_URL=vehicles.db ev-server
 ## Endpoints
 
 - `GET /api/v1/health` - Health check
-- `GET /api/v1/vehicles` - List vehicles with filters
-- `GET /api/v1/vehicles/{make}/{model}/{year}` - Get vehicle details
-- `GET /api/v1/vehicles/{make}/{model}/{year}/variants` - List variants
-- `GET /api/v1/makes` - List manufacturers
-- `GET /api/v1/makes/{make}/models` - List models
-- `GET /api/v1/search?q=query` - Full-text search
+- `GET /api/v1/vehicles/list` - List vehicles with filters and pagination
+- `GET /api/v1/vehicles/code/{code}` - Get vehicle by unique code
+- `GET /api/v1/vehicles/search?q=query` - Full-text search
+- `GET /api/v1/makes/list` - List manufacturers with model names
 
 ## OpenAPI Documentation
 

docs/api/GET_STARTED.md

@@ -89,10 +89,10 @@ Test endpoints:
 
 ```bash
 curl http://localhost:3000/api/v1/health
-curl http://localhost:3000/api/v1/makes
-curl http://localhost:3000/api/v1/vehicles
-curl http://localhost:3000/api/v1/vehicles/tesla/model_3/2024
-curl "http://localhost:3000/api/v1/search?q=dolphin"
+curl http://localhost:3000/api/v1/makes/list
+curl http://localhost:3000/api/v1/vehicles/list
+curl http://localhost:3000/api/v1/vehicles/code/tesla:model_3:2024:model_3
+curl "http://localhost:3000/api/v1/vehicles/search?q=dolphin"
 ```
 
 Swagger UI is available at: `http://localhost:3000/docs`

docs/api/PROBLEM_DETAILS_RFC_7807.md

@@ -25,8 +25,8 @@ All error responses return a JSON object with these fields:
   "type": "https://github.com/open-ev-data/open-ev-data-api/blob/main/docs/API_ERRORS.md#errorsnot-found",
   "title": "Resource Not Found",
   "status": 404,
-  "detail": "Vehicle not found: tesla/model_x/2099",
-  "instance": "/api/v1/vehicles/tesla/model_x/2099"
+  "detail": "Vehicle not found with code: tesla:model_x:2099:model_x",
+  "instance": "/api/v1/vehicles/code/tesla:model_x:2099:model_x"
 }
 ```
 

docs/api/TESTING.md

@@ -114,14 +114,14 @@ Test complete API workflows from request to response.
 **Example:**
 ```rust
 #[tokio::test]
-async fn test_get_vehicle_success() {
-    let response = client.get("/api/v1/vehicles/tesla/model_3/2024").await;
+async fn test_get_vehicle_by_code_success() {
+    let response = client.get("/api/v1/vehicles/code/tesla:model_3:2024:model_3").await;
     assert_eq!(response.status(), 200);
 }
 
 #[tokio::test]
-async fn test_get_vehicle_not_found() {
-    let response = client.get("/api/v1/vehicles/invalid/invalid/9999").await;
+async fn test_get_vehicle_by_code_not_found() {
+    let response = client.get("/api/v1/vehicles/code/invalid:code:2024:unknown").await;
     assert_eq!(response.status(), 404);
     let body: ProblemDetails = response.json().await;
     assert!(body.error_type.contains("not-found"));

docs/api/index.md

@@ -47,12 +47,10 @@ This repository provides a **production-ready REST API** for querying electric v
 | Endpoint | Description |
 |----------|-------------|
 | `GET /api/v1/health` | Health check |
-| `GET /api/v1/vehicles` | List vehicles with filters |
-| `GET /api/v1/vehicles/{make}/{model}/{year}` | Get vehicle details |
-| `GET /api/v1/vehicles/{make}/{model}/{year}/variants` | List variants |
-| `GET /api/v1/makes` | List manufacturers |
-| `GET /api/v1/makes/{make}/models` | List models |
-| `GET /api/v1/search?q=query` | Full-text search |
+| `GET /api/v1/vehicles/list` | List vehicles with filters and pagination |
+| `GET /api/v1/vehicles/code/{code}` | Get vehicle by unique code |
+| `GET /api/v1/vehicles/search?q=query` | Full-text search |
+| `GET /api/v1/makes/list` | List manufacturers with model names |
 
 ## Use Cases