🚗 Cars API Documentation

Base URL: https://api.example.com/v1

Endpoints

GET/cars

Retrieve a list of all cars.

Query Parameters

Parameter Type Required Description
page integer No Page number (default: 1)
limit integer No Items per page (default: 10, max: 100)
brand string No Filter by car brand

Response (200 OK)

{
  "data": [
    {
      "id": 1,
      "brand": "Toyota",
      "model": "Camry",
      "year": 2023,
      "color": "Silver",
      "price": 28000,
      "mileage": 15000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50
  }
}

GET/cars/{id}

Retrieve details of a specific car by ID.

Path Parameters

Parameter Type Required Description
id integer Yes Unique car identifier

Response (200 OK)

{
  "id": 1,
  "brand": "Toyota",
  "model": "Camry",
  "year": 2023,
  "color": "Silver",
  "price": 28000,
  "mileage": 15000,
  "vin": "1HGBH41JXMN109186",
  "transmission": "Automatic",
  "fuel_type": "Gasoline"
}

Error Response (404 Not Found)

{
  "error": "Car not found",
  "message": "No car exists with the specified ID"
}

POST/cars

Create a new car entry.

Request Body

{
  "brand": "Honda",
  "model": "Accord",
  "year": 2023,
  "color": "Blue",
  "price": 30000,
  "mileage": 0,
  "vin": "1HGCV1F3XLA012345",
  "transmission": "Automatic",
  "fuel_type": "Hybrid"
}

Response (201 Created)

{
  "id": 51,
  "brand": "Honda",
  "model": "Accord",
  "year": 2023,
  "color": "Blue",
  "price": 30000,
  "mileage": 0,
  "vin": "1HGCV1F3XLA012345",
  "transmission": "Automatic",
  "fuel_type": "Hybrid",
  "created_at": "2023-12-01T10:30:00Z"
}

PUT/cars/{id}

Update an existing car entry.

Path Parameters

Parameter Type Required Description
id integer Yes Unique car identifier

Request Body

{
  "price": 27500,
  "mileage": 20000
}

Response (200 OK)

{
  "id": 1,
  "brand": "Toyota",
  "model": "Camry",
  "year": 2023,
  "color": "Silver",
  "price": 27500,
  "mileage": 20000,
  "updated_at": "2023-12-01T11:00:00Z"
}

DELETE/cars/{id}

Delete a car entry.

Path Parameters

Parameter Type Required Description
id integer Yes Unique car identifier

Response (204 No Content)

No content returned

Data Model

Car Object

Field Type Description
id integer Unique identifier
brand string Car manufacturer
model string Car model name
year integer Manufacturing year
color string Exterior color
price number Price in USD
mileage integer Odometer reading in miles
vin string Vehicle Identification Number
transmission string Transmission type (Automatic/Manual)
fuel_type string Fuel type (Gasoline/Diesel/Hybrid/Electric)