Pets API - Adoptme API

Overview

The Pets API provides endpoints for managing pets in the Adoptme system. You can create, retrieve, update, and delete pet records. The API also supports image uploads for pets using multipart/form-data. Base Path: /api/pets Source Files:

Routes: src/routes/pets.router.js
Controller: src/controllers/pets.controller.js
Model: src/dao/models/Pet.js

Pet Model

The Pet schema includes the following fields:

_id

ObjectId

required

MongoDB-generated unique identifier

name

string

required

Pet’s name

specie

string

required

Pet’s species (e.g., “dog”, “cat”, “bird”)

birthDate

Date

Pet’s birth date

adopted

boolean

default:"false"

Whether the pet has been adopted

owner

ObjectId

Reference to the User who adopted this pet (only set when adopted is true)

image

string

File path to the pet’s image (set when using the withimage endpoint)

Get All Pets

curl -X GET http://localhost:8080/api/pets

Endpoint

GET /api/pets

Retrieves a list of all pets in the system.

Response

status

string

“success”

payload

array

Array of pet objects

Example Response

{
  "status": "success",
  "payload": [
    {
      "_id": "65abc123def456789",
      "name": "Max",
      "specie": "dog",
      "birthDate": "2020-05-15T00:00:00.000Z",
      "adopted": false,
      "image": "/src/public/img/max_1234567890.jpg"
    },
    {
      "_id": "65abc123def456790",
      "name": "Luna",
      "specie": "cat",
      "birthDate": "2021-08-22T00:00:00.000Z",
      "adopted": true,
      "owner": "6893eaba2ac0b16fa177be7a"
    }
  ]
}

Error Responses

Show 500 Internal Server Error

Ha ocurrido un error en la petición, por favor ver detalle: [error]

Create Pet

curl -X POST http://localhost:8080/api/pets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buddy",
    "specie": "dog",
    "birthDate": "2022-03-10"
  }'

Endpoint

POST /api/pets

Creates a new pet without an image.

Request Body

name

string

required

Pet’s name

specie

string

required

Pet’s species (e.g., “dog”, “cat”, “bird”, “rabbit”)

birthDate

string

required

Pet’s birth date (ISO 8601 format or any valid date string)

Example Request Body

{
  "name": "Buddy",
  "specie": "dog",
  "birthDate": "2022-03-10"
}

Response

status

string

“success”

payload

object

The created pet object

Example Response

{
  "status": "success",
  "payload": {
    "_id": "65abc123def456791",
    "name": "Buddy",
    "specie": "dog",
    "birthDate": "2022-03-10T00:00:00.000Z",
    "adopted": false,
    "pets": []
  }
}

Error Responses

Show 400 Incomplete Values

{
  "status": "error",
  "error": "Incomplete values"
}

Returned when name, specie, or birthDate is missing.

Show 500 Internal Server Error

Ha ocurrido un error en la petición, por favor ver detalle: [error]

Create Pet with Image

curl -X POST http://localhost:8080/api/pets/withimage \
  -F "name=Bella" \
  -F "specie=cat" \
  -F "birthDate=2021-07-20" \
  -F "image=@/path/to/pet-photo.jpg"

Endpoint

POST /api/pets/withimage

Creates a new pet with an uploaded image. This endpoint uses multipart/form-data for file uploads.

This endpoint uses Multer middleware for handling file uploads. The image is stored in /src/public/img/ with a unique filename.

Request Body (multipart/form-data)

name

string

required

Pet’s name

specie

string

required

Pet’s species

birthDate

string

required

Pet’s birth date

image

file

required

Image file (processed by multer middleware with field name ‘image’)

Response

status

string

“success”

payload

object

The created pet object with image path

Example Response

{
  "status": "success",
  "payload": {
    "_id": "65abc123def456792",
    "name": "Bella",
    "specie": "cat",
    "birthDate": "2021-07-20T00:00:00.000Z",
    "adopted": false,
    "image": "/home/user/workspace/source/src/public/img/bella_1710345678901.jpg"
  }
}

Implementation Details

The image path is constructed using:

image: `${__dirname}/../public/img/${file.filename}`

Where file.filename is generated by the Multer uploader middleware defined in src/utils/uploader.js.

Error Responses

Show 400 Incomplete Values

{
  "status": "error",
  "error": "Incomplete values"
}

Returned when name, specie, or birthDate is missing.

Show 500 Internal Server Error

Ha ocurrido un error en la petición, por favor ver detalle: [error]

Update Pet

curl -X PUT http://localhost:8080/api/pets/65abc123def456791 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buddy Jr.",
    "adopted": true
  }'

Endpoint

PUT /api/pets/:pid

Updates an existing pet’s information.

Path Parameters

pid

string

required

The unique identifier (MongoDB ObjectId) of the pet to update

Request Body

Send any pet fields you want to update. All fields are optional:

name

string

Updated pet name

specie

string

Updated species

birthDate

string

Updated birth date

adopted

boolean

Updated adoption status

owner

string

Updated owner ObjectId

image

string

Updated image path

Example Request Body

{
  "name": "Buddy Jr.",
  "adopted": true,
  "owner": "6893eaba2ac0b16fa177be7a"
}

Manually updating the adopted status and owner field should typically be done through the Adoptions API to ensure data consistency.

Response

status

string

“success”

message

string

“pet updated”

Example Response

{
  "status": "success",
  "message": "pet updated"
}

Error Responses

Show 500 Internal Server Error

Ha ocurrido un error en la petición, por favor ver detalle: [error]

Delete Pet

curl -X DELETE http://localhost:8080/api/pets/65abc123def456791

Endpoint

DELETE /api/pets/:pid

Deletes a pet from the system.

Path Parameters

pid

string

required

The unique identifier (MongoDB ObjectId) of the pet to delete

Response

status

string

“success”

message

string

“pet deleted”

Example Response

{
  "status": "success",
  "message": "pet deleted"
}

Error Responses

Show 500 Internal Server Error

Ha ocurrido un error en la petición, por favor ver detalle: [error]

Deleting a pet does not automatically update related users or adoptions. You may need to handle these relationships separately.

Implementation Details

Controller Source

The Pets controller (src/controllers/pets.controller.js) implements the following key logic:

Show createPet - Lines 14-24

const createPet = async(req,res)=> {
    try {
        const {name,specie,birthDate} = req.body;
        if(!name||!specie||!birthDate) return res.status(400).send({status:"error",error:"Incomplete values"})
        const pet = PetDTO.getPetInputFrom({name,specie,birthDate});
        const result = await petsService.create(pet);
        res.send({status:"success",payload:result})        
    } catch (error) {
        res.status(500).send("Ha ocurrido un error en la petición, por favor ver detalle: ",error)    
    }
}

Show createPetWithImage - Lines 48-67

const createPetWithImage = async(req,res) =>{
    try {
        const file = req.file;
        const {name,specie,birthDate} = req.body;
        if(!name||!specie||!birthDate) return res.status(400).send({status:"error",error:"Incomplete values"})
        console.log(file);
        const pet = PetDTO.getPetInputFrom({
            name,
            specie,
            birthDate,
            image:`${__dirname}/../public/img/${file.filename}`
        });
        console.log(pet);
        const result = await petsService.create(pet);
        res.send({status:"success",payload:result})        
    } catch (error) {
        res.status(500).send("Ha ocurrido un error en la petición, por favor ver detalle: ",error)
    }
}

Router Configuration

Routes are defined in src/routes/pets.router.js:

router.get('/', petsController.getAllPets);
router.post('/', petsController.createPet);
router.post('/withimage', uploader.single('image'), petsController.createPetWithImage);
router.put('/:pid', petsController.updatePet);
router.delete('/:pid', petsController.deletePet);

Note the Multer middleware (uploader.single('image')) on the withimage route.

Pet DTO

The Pet DTO (src/dto/Pet.dto.js) transforms input data before saving to the database, ensuring consistent data structure and default values.

Adoptions API

Create adoption records linking pets to users

Mocks API

Generate mock pet data for testing

Endpoints

​Overview

​Pet Model

​Get All Pets

​Endpoint

​Response

​Example Response

​Error Responses

​Create Pet

​Endpoint

​Request Body

​Example Request Body

​Response

​Example Response

​Error Responses

​Create Pet with Image

​Endpoint

​Request Body (multipart/form-data)

​Response

​Example Response

​Implementation Details

​Error Responses

​Update Pet

​Endpoint

​Path Parameters

​Request Body

​Example Request Body

​Response

​Example Response

​Error Responses

​Delete Pet

​Endpoint

​Path Parameters

​Response

​Example Response

​Error Responses

​Implementation Details

​Controller Source

​Router Configuration

​Pet DTO

​Related Endpoints

Adoptions API

Mocks API

Build docs developers (and LLMs) love

Overview

Pet Model

Get All Pets

Endpoint

Response

Example Response

Error Responses

Create Pet

Endpoint

Request Body

Example Request Body

Response

Example Response

Error Responses

Create Pet with Image

Endpoint

Request Body (multipart/form-data)

Response

Example Response

Implementation Details

Error Responses

Update Pet

Endpoint

Path Parameters

Request Body

Example Request Body

Response

Example Response

Error Responses

Delete Pet

Endpoint

Path Parameters

Response

Example Response

Error Responses

Implementation Details

Controller Source

Router Configuration

Pet DTO

Related Endpoints