Skip to main content

​
Overview

The Vehicle Images API allows you to manage images associated with vehicles in the DriveX system. Each vehicle can have multiple images (up to 15), with one designated as the main/primary image.

​
Model Structure

​
VehicleImage

The VehicleImage entity represents an image associated with a vehicle.
​
id
Long
Unique identifier for the vehicle image
​
vehicle
Vehicle
The associated vehicle (ManyToOne relationship). This field is excluded from JSON responses to prevent circular references.
​
imageUrl
String
URL or path to the image file
​
isMain
boolean
default:"false"
Indicates whether this is the primary/main image for the vehicle

​
Relationship with Vehicle

Vehicle images use a ManyToOne relationship with the Vehicle entity:
  • Each VehicleImage belongs to exactly one Vehicle
  • Each Vehicle can have multiple VehicleImage records (OneToMany from Vehicle’s perspective)
  • Maximum of 15 images per vehicle
  • The vehicle field in the response is excluded via @JsonIgnore to prevent circular serialization issues

​
Endpoints

​
Upload Vehicle Image

curl -X POST http://localhost:8080/api/vehicles/{id}/images \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/images/car1.jpg",
    "isMain": true
  }'
Add a new image to a vehicle. Path Parameters
​
id
Long
required
The ID of the vehicle to add the image to
Request Body
​
imageUrl
String
required
URL or path to the vehicle image
​
isMain
boolean
default:"false"
Set to true to mark this as the primary image for the vehicle
Response Returns the created VehicleImage object.
​
id
Long
ID of the newly created image record
​
imageUrl
String
The URL of the uploaded image
​
isMain
boolean
Whether this is the main image
Validation
  • Maximum of 15 images per vehicle
  • Vehicle must exist (returns error if not found)

​
List Vehicle Images

curl -X GET http://localhost:8080/api/vehicles/{id}/images
Retrieve all images associated with a specific vehicle. Path Parameters
​
id
Long
required
The ID of the vehicle whose images to retrieve
Response Returns an array of VehicleImage objects. 
[
  {
    "id": 1,
    "imageUrl": "https://example.com/images/car1-main.jpg",
    "isMain": true
  },
  {
    "id": 2,
    "imageUrl": "https://example.com/images/car1-interior.jpg",
    "isMain": false
  }
]

​
Error Handling

ErrorDescription
IllegalStateExceptionThrown when attempting to add more than 15 images to a vehicle
RuntimeExceptionThrown when the specified vehicle ID does not exist

​
Business Rules

  1. Image Limit: Each vehicle can have a maximum of 15 images
  2. Main Image: At least one image should typically be marked as isMain: true for display purposes
  3. Vehicle Reference: Images must be associated with an existing vehicle
  4. Database Table: Images are stored in the vehicle_images table

Build docs developers (and LLMs) love

Get started for freeTalk to us