Skip to main content

​
Overview

The Vehicles API allows you to manage vehicle registrations for residents in the Happy Habitat system. All endpoints require authentication via bearer token. Base URL: /api/vehicles Authentication: Required (Bearer token)

​
Get All Vehicles

​
GET
/api/vehicles
Retrieves all vehicles in the system.

​
Response

​
vehicles
array
Array of vehicle objects

​
Example Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
    "residentName": "John Doe",
    "brand": "Toyota",
    "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "vehicleTypeName": "Car",
    "model": "Camry",
    "year": 2022,
    "color": "Silver",
    "licensePlate": "ABC-1234",
    "createdAt": "2024-03-04T10:30:00Z"
  }
]

​
Get Vehicle by ID

​
GET
/api/vehicles/{id}
Retrieves a specific vehicle by its unique identifier.

​
Path Parameters

​
id
string (GUID)
required
The unique identifier of the vehicle

​
Response

Returns a single vehicle object with the same structure as described above.

​
Status Codes

  • 200 OK - Vehicle found and returned
  • 404 Not Found - Vehicle with the specified ID does not exist

​
Example Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "residentName": "John Doe",
  "brand": "Honda",
  "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "vehicleTypeName": "Car",
  "model": "Civic",
  "year": 2021,
  "color": "Blue",
  "licensePlate": "XYZ-5678",
  "createdAt": "2024-02-15T14:20:00Z"
}

​
Get Vehicles by Resident

​
GET
/api/vehicles/resident/{residentId}
Retrieves all vehicles belonging to a specific resident.

​
Path Parameters

​
residentId
string (GUID)
required
The unique identifier of the resident

​
Response

Returns an array of vehicle objects associated with the specified resident.

​
Example Response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
    "residentName": "John Doe",
    "brand": "Ford",
    "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "vehicleTypeName": "Truck",
    "model": "F-150",
    "year": 2023,
    "color": "Black",
    "licensePlate": "DEF-9012",
    "createdAt": "2024-01-10T09:15:00Z"
  }
]

​
Create Vehicle

​
POST
/api/vehicles
Creates a new vehicle registration.

​
Request Body

​
residentId
string (GUID)
required
ID of the resident who owns the vehicle
​
brand
string
required
Vehicle manufacturer brand
​
vehicleTypeId
string (GUID)
required
ID of the vehicle type
​
model
string
required
Vehicle model name
​
year
integer
required
Manufacturing year
​
color
string
required
Vehicle color
​
licensePlate
string
required
License plate number (must be unique)

​
Example Request

{
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "brand": "Tesla",
  "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "model": "Model 3",
  "year": 2024,
  "color": "White",
  "licensePlate": "GHI-3456"
}

​
Response

Returns the created vehicle object with a generated id and createdAt field.

​
Status Codes

  • 201 Created - Vehicle successfully created
  • 400 Bad Request - Invalid input data or duplicate license plate

​
Example Response

{
  "id": "5fa85f64-5717-4562-b3fc-2c963f66afa8",
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "residentName": "John Doe",
  "brand": "Tesla",
  "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "vehicleTypeName": "Car",
  "model": "Model 3",
  "year": 2024,
  "color": "White",
  "licensePlate": "GHI-3456",
  "createdAt": "2024-03-04T11:45:00Z"
}

​
Update Vehicle

​
PUT
/api/vehicles/{id}
Updates an existing vehicle’s information.

​
Path Parameters

​
id
string (GUID)
required
The unique identifier of the vehicle to update

​
Request Body

​
residentId
string (GUID)
required
ID of the resident who owns the vehicle
​
brand
string
required
Vehicle manufacturer brand
​
vehicleTypeId
string (GUID)
required
ID of the vehicle type
​
model
string
required
Vehicle model name
​
year
integer
required
Manufacturing year
​
color
string
required
Vehicle color
​
licensePlate
string
required
License plate number

​
Example Request

{
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "brand": "Honda",
  "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "model": "Civic",
  "year": 2021,
  "color": "Red",
  "licensePlate": "JKL-7890"
}

​
Response

Returns the updated vehicle object.

​
Status Codes

  • 200 OK - Vehicle successfully updated
  • 404 Not Found - Vehicle with the specified ID does not exist
  • 400 Bad Request - Invalid input data

​
Example Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "residentName": "John Doe",
  "brand": "Honda",
  "vehicleTypeId": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "vehicleTypeName": "Car",
  "model": "Civic",
  "year": 2021,
  "color": "Red",
  "licensePlate": "JKL-7890",
  "createdAt": "2024-02-15T14:20:00Z"
}

​
Delete Vehicle

​
DELETE
/api/vehicles/{id}
Deletes a vehicle from the system.

​
Path Parameters

​
id
string (GUID)
required
The unique identifier of the vehicle to delete

​
Response

No content returned on successful deletion.

​
Status Codes

  • 204 No Content - Vehicle successfully deleted
  • 404 Not Found - Vehicle with the specified ID does not exist

​
Error Responses

All endpoints may return the following error responses:

​
401 Unauthorized

{
  "message": "Unauthorized access. Please provide a valid authentication token."
}

​
400 Bad Request

{
  "message": "Invalid operation: License plate already exists."
}

​
404 Not Found

{
  "message": "Vehicle not found."
}

​
Notes

  • All vehicle operations require proper authentication
  • License plates must be unique across the system
  • Vehicle types must exist in the system before creating a vehicle
  • The resident must exist before registering a vehicle
  • The createdAt timestamp is automatically generated upon creation

Build docs developers (and LLMs) love

Get started for freeTalk to us