PawFinder Service API

Connecting paws with people

© 2025. RJ Rodriguez. All rights reserved.

Paw pair

Mark a pet as adopted

Update a pet profile status when finalizing adoptions. Learn how to update pet records using the PATCH method and manage adoption workflows from the shelter perspective.

How the adoption workflow works

The PawFinder Service API provides an endpoint for updating pet profiles as adoptions progress.

PawFinder uses json-server with basic status updates. The diagram below shows what a production shelter management system might look like when tracking pet adoptions:

graph LR
    A["Step 1:<br/>Log In<br/>Shelter Admin"] -->|Access Inventory| B["Step 2:<br/>View Pet<br/>Records"]
    B -->|Select Pet| C["Step 3:<br/>Update Status<br/>From Available<br/>to Adopted"]
    C -->|Confirm Update| D["Step 4:<br/>System Confirms<br/>Change Saved"]
    D -->|Notify Adopters| E["Step 5:<br/>Pet Removed<br/>From Search<br/>Results"]
    
    style A fill:#9989c4,stroke:#333,stroke-width:2px,color:#fff
    style B fill:#88b2c4,stroke:#333,stroke-width:2px,color:#fff
    style C fill:#cc848a,stroke:#333,stroke-width:2px,color:#000
    style D fill:#c5d3a6,stroke:#333,stroke-width:2px,color:#000
    style E fill:#88b2c4,stroke:#333,stroke-width:2px,color:#fff

Prerequisites

Endpoint structure

# Recommended base_url = http://localhost:3000
PATCH {base_url}/pets/{id}

Path parameters

Parameter Type Description Example
id integer Pet’s unique identifier 1, 2, 3, 4

Authentication

Required - include an API token in the Authorization header:

Authorization: Bearer API_TOKEN

Request body

Provide a JSON object with the fields to update. Only include fields that are changing, as PATCH only updates the specified fields and leaves the others unchanged.

Field Type Description Example
status string Pet’s current adoption stage available, pending, adopted
medical object Pet’s medical information {"spayed_neutered": true, "vaccinations": [...]}

Understanding state transitions

Pet status moves through a defined workflow. Understanding these transitions help shelter staff manage adoption inquiries efficiently:

stateDiagram-v2
    [*] --> available: Pet enters shelter
    
    available --> pending: Received
    available --> available: Rejected
    
    pending --> adopted: Finalized
    pending --> available: Rejected
    
    adopted --> [*]: Pet left shelter
    
    style available fill:#88b2c4,stroke:#333,stroke-width:2px,color:#fff
    style pending fill:#c5d3a6,stroke:#333,stroke-width:2px,color:#000
    style adopted fill:#cc848a,stroke:#333,stroke-width:2px,color:#000

State meanings:

Transition rules:

Start the service

# Run from the pawfinder-service root directory
npm start

Review Find the Perfect Pet for an alternative startup method.

Call the service

Use cURL commands or the Postman desktop app to make requests. For detailed Postman setup steps, visit the Installation Guide.

Example 1: mark a pet as adopted

An adopter completes paperwork for Luna, pet profile id = 1, at Dallas Animal Services. Update Luna’s status to reflect the finalized adoption.

Use cURL

curl -X PATCH "{base_url}/pets/1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_TOKEN" \
  -d '{
    "status": "adopted"
  }'

Use Postman desktop app

Set up a PATCH request to {base_url}/pets/1 with the request body:

{
  "status": "adopted"
}

Response 200 OK - the response confirms that Luna’s status changed from available to adopted.

{
  "name": "Luna",
  "species": "cat",
  "breed": "Domestic Shorthair",
  "age_months": 18,
  "gender": "female",
  "size": "small",
  "temperament": "playful, affectionate",
  "medical": {
    "spayed_neutered": true,
    "vaccinations": ["fvrcp", "rabies"]
  },
  "description": "Luna is a playful tabby who loves interactive toys and sunny windows.",
  "shelter_id": 1,
  "status": "adopted",
  "intake_date": "2025-09-01",
  "id": 1
}

Example 2: update different fields during adoption finalization

When finalizing an adoption, update both status and any medical procedures completed at the shelter.

curl -X PATCH "{base_url}/pets/4" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_TOKEN" \
  -d '{
    "status": "adopted",
    "medical": {
      "spayed_neutered": true,
      "vaccinations": ["rabies", "dhpp", "leptospirosis"]
    }'

Response 200 OK - Bella’s record now reflects both adopted and the completed medical procedures.

{
  "name": "Bella",
  "species": "dog",
  ...
  "medical": {
    "spayed_neutered": true,
    "vaccinations": ["rabies", "dhpp", "leptospirosis"]
  },
  ...
  "status": "adopted",
  ...
}

Example 3: move pet to status: pending during an adoption form review

Block other applicants from inquiring about a pet while an adoption form is under review. Update the pet status to pending.

curl -X PATCH "{base_url}/pets/2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_TOKEN" \
  -d '{
    "status": "pending"
  }'

Response 200 OK - Max is now marked as pending while the shelter reviews a potential adopter’s form.

{
  "name": "Max",
  ...
  "status": "pending",
  ...
}

Common error responses

Code Scenario Response
400 Invalid values { "error": "Bad Request", "message": "Invalid value for 'status'." ...}
401 Invalid API token { "error": "Unauthorized", "message": "Authentication token is required for this operation." ...}
404 Invalid id { "error": "Not Found", "message": "Pet with 'id' 999 not found." ...}

Best practices

Troubleshooting

Next steps