Skip to main content

​
Overview

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

​
Get All Pets

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

​
Response

​
pets
array
Array of pet objects

​
Example Response

[
  {
    "id": "7fa85f64-5717-4562-b3fc-2c963f66afa9",
    "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
    "residentName": "Jane Smith",
    "name": "Max",
    "species": "Dog",
    "breed": "Golden Retriever",
    "age": 3,
    "color": "Golden",
    "createdAt": "2024-03-01T10:00:00Z"
  }
]

​
Get Pet by ID

​
GET
/api/pets/{id}
Retrieves a specific pet by its unique identifier.

​
Path Parameters

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

​
Response

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

​
Status Codes

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

​
Example Response

{
  "id": "7fa85f64-5717-4562-b3fc-2c963f66afa9",
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "residentName": "Jane Smith",
  "name": "Luna",
  "species": "Cat",
  "breed": "Persian",
  "age": 2,
  "color": "White",
  "createdAt": "2024-02-20T15:30:00Z"
}

​
Get Pets by Resident

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

​
Path Parameters

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

​
Response

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

​
Example Response

[
  {
    "id": "7fa85f64-5717-4562-b3fc-2c963f66afa9",
    "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
    "residentName": "Jane Smith",
    "name": "Buddy",
    "species": "Dog",
    "breed": "Labrador",
    "age": 5,
    "color": "Black",
    "createdAt": "2024-01-15T09:00:00Z"
  },
  {
    "id": "9fb85f64-5717-4562-b3fc-2c963f66afb1",
    "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
    "residentName": "Jane Smith",
    "name": "Whiskers",
    "species": "Cat",
    "breed": "Siamese",
    "age": 4,
    "color": "Cream with dark points",
    "createdAt": "2024-01-20T11:30:00Z"
  }
]

​
Create Pet

​
POST
/api/pets
Creates a new pet registration.

​
Request Body

​
residentId
string (GUID)
required
ID of the resident who owns the pet
​
name
string
required
Pet’s name
​
species
string
required
Pet species (e.g., Dog, Cat, Bird, Fish)
​
breed
string
required
Pet breed or type
​
age
integer
required
Pet’s age in years
​
color
string
required
Pet’s color or distinctive markings

​
Example Request

{
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "name": "Charlie",
  "species": "Dog",
  "breed": "Beagle",
  "age": 1,
  "color": "Tricolor (brown, black, white)"
}

​
Response

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

​
Status Codes

  • 201 Created - Pet successfully registered
  • 400 Bad Request - Invalid input data

​
Example Response

{
  "id": "2fb85f64-5717-4562-b3fc-2c963f66afc3",
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "residentName": "Jane Smith",
  "name": "Charlie",
  "species": "Dog",
  "breed": "Beagle",
  "age": 1,
  "color": "Tricolor (brown, black, white)",
  "createdAt": "2024-03-04T12:00:00Z"
}

​
Update Pet

​
PUT
/api/pets/{id}
Updates an existing pet’s information.

​
Path Parameters

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

​
Request Body

​
residentId
string (GUID)
required
ID of the resident who owns the pet
​
name
string
required
Pet’s name
​
species
string
required
Pet species
​
breed
string
required
Pet breed
​
age
integer
required
Pet’s age in years
​
color
string
required
Pet’s color or markings

​
Example Request

{
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "name": "Charlie",
  "species": "Dog",
  "breed": "Beagle",
  "age": 2,
  "color": "Tricolor with white chest patch"
}

​
Response

Returns the updated pet object.

​
Status Codes

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

​
Example Response

{
  "id": "2fb85f64-5717-4562-b3fc-2c963f66afc3",
  "residentId": "8b92c1e4-2a3d-4f5e-9c7b-1d8e5f6a3b2c",
  "residentName": "Jane Smith",
  "name": "Charlie",
  "species": "Dog",
  "breed": "Beagle",
  "age": 2,
  "color": "Tricolor with white chest patch",
  "createdAt": "2024-03-04T12:00:00Z"
}

​
Delete Pet

​
DELETE
/api/pets/{id}
Deletes a pet from the system.

​
Path Parameters

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

​
Response

No content returned on successful deletion.

​
Status Codes

  • 204 No Content - Pet successfully deleted
  • 404 Not Found - Pet 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: Required fields are missing."
}

​
404 Not Found

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

​
Notes

  • All pet operations require proper authentication
  • The resident must exist before registering a pet
  • Age is stored in years; use 0 for pets less than one year old
  • Consider community pet policies when registering pets
  • Multiple pets can be registered per resident
  • The createdAt timestamp is automatically generated upon creation

Build docs developers (and LLMs) love

Get started for freeTalk to us