202 lines
4.9 KiB
Markdown
202 lines
4.9 KiB
Markdown
# BREEDR API Documentation (v0.8.0)
|
|
|
|
Base URL: `/api`
|
|
|
|
All endpoints return JSON responses. Errors follow the format `{ "error": "message" }`.
|
|
|
|
---
|
|
|
|
## 1. Dogs (`/api/dogs`)
|
|
|
|
Manage individual dogs in the kennel.
|
|
|
|
### `GET /`
|
|
Get active kennel dogs.
|
|
- **Query Params**:
|
|
- `include_external=1`: Include external dogs (studs/others)
|
|
- `external_only=1`: Only show external dogs
|
|
- **Response**: Array of [Dog](#dog-object) objects with `sire` and `dam` attached.
|
|
|
|
### `GET /:id`
|
|
Get single dog details.
|
|
- **Response**: [Dog](#dog-object) object including `sire`, `dam`, and `offspring` array.
|
|
|
|
### `POST /`
|
|
Create a new dog.
|
|
- **Body**: See [Dog](#dog-object) fields. `name`, `breed`, `sex` are required.
|
|
- **Response**: The created Dog object.
|
|
|
|
### `PUT /:id`
|
|
Update an existing dog.
|
|
- **Body**: Dog fields to update.
|
|
- **Response**: The updated Dog object.
|
|
|
|
### `DELETE /:id`
|
|
Permanently delete a dog and its related records (health, heat, parents).
|
|
- **Response**: `{ "success": true, "message": "..." }`
|
|
|
|
### `POST /:id/photos`
|
|
Upload a photo for a dog.
|
|
- **Form-Data**: `photo` (file)
|
|
- **Response**: `{ "url": "...", "photos": [...] }`
|
|
|
|
### `DELETE /:id/photos/:photoIndex`
|
|
Delete a specific photo from a dog's photo array.
|
|
- **Response**: `{ "photos": [...] }`
|
|
|
|
---
|
|
|
|
## 2. Litters (`/api/litters`)
|
|
|
|
Manage breeding litters and puppy logs.
|
|
|
|
### `GET /`
|
|
Get all litters.
|
|
- **Response**: Array of [Litter](#litter-object) objects with sire/dam names and puppies.
|
|
|
|
### `GET /:id`
|
|
Get single litter details.
|
|
- **Response**: [Litter](#litter-object) object.
|
|
|
|
### `POST /`
|
|
Create a new litter.
|
|
- **Body**: `sire_id`, `dam_id`, `breeding_date` (required), `whelping_date`, `puppy_count`, `notes`.
|
|
- **Response**: The created Litter object.
|
|
|
|
### `PUT /:id`
|
|
Update litter details.
|
|
|
|
### `POST /:id/puppies/:puppyId`
|
|
Link a dog to a litter as a puppy.
|
|
- **Side Effect**: Automatically sets the litter's sire and dam as the puppy's parents.
|
|
|
|
### `DELETE /:id/puppies/:puppyId`
|
|
Remove a puppy from a litter (sets `litter_id` to NULL).
|
|
|
|
### `GET /:litterId/puppies/:puppyId/logs`
|
|
Get weight and health logs for a puppy.
|
|
|
|
### `POST /:litterId/puppies/:puppyId/logs`
|
|
Add a weight/health log entry.
|
|
- **Body**: `record_date` (required), `weight_oz`, `weight_lbs`, `notes`, `record_type`.
|
|
|
|
---
|
|
|
|
## 3. Health (`/api/health`)
|
|
|
|
Manage OFA clearances and veterinary records.
|
|
|
|
### `GET /dog/:dogId`
|
|
Get all health records for a dog.
|
|
|
|
### `GET /dog/:dogId/clearance-summary`
|
|
Get GRCA core clearance status (Hip, Elbow, Heart, Eyes).
|
|
- **Response**: `{ summary, grca_eligible, age_eligible, chic_number }`
|
|
|
|
### `GET /dog/:dogId/chic-eligible`
|
|
Check if a dog has all required CHIC tests.
|
|
|
|
### `POST /`
|
|
Create health record.
|
|
- **Body**: `dog_id`, `record_type`, `test_date` (required), `test_type`, `test_name`, `ofa_result`, `ofa_number`, etc.
|
|
|
|
---
|
|
|
|
## 4. Genetics (`/api/genetics`)
|
|
|
|
Manage DNA panel results and breeding risks.
|
|
|
|
### `GET /dog/:dogId`
|
|
Get the full genetic panel for a dog. Returns `tests` (actual records) and `panel` (full list including `not_tested` placeholders).
|
|
|
|
### `GET /pairing-risk?sireId=X&damId=Y`
|
|
Check genetic compatibility between two dogs.
|
|
- **Response**: `{ risks: [...], safe_to_pair: boolean }`
|
|
|
|
### `POST /`
|
|
Add a genetic test result.
|
|
- **Body**: `dog_id`, `marker`, `result` (clear|carrier|affected|not_tested).
|
|
|
|
---
|
|
|
|
## 5. Breeding (`/api/breeding`)
|
|
|
|
Track heat cycles and whelping projections.
|
|
|
|
### `GET /heat-cycles/active`
|
|
Get currently active heat cycles.
|
|
|
|
### `GET /heat-cycles/:id/suggestions`
|
|
Get optimal breeding window (days 9-15) and whelping projections.
|
|
|
|
### `POST /heat-cycles`
|
|
Log a new heat cycle. Dog must be female.
|
|
|
|
### `GET /whelping-calculator?breeding_date=YYYY-MM-DD`
|
|
Standalone tool to calculate expected whelping window.
|
|
|
|
---
|
|
|
|
## 6. Pedigree (`/api/pedigree`)
|
|
|
|
Advanced ancestry and COI calculations.
|
|
|
|
### `GET /:id?generations=N`
|
|
Get an interactive pedigree tree (ancestors). Default 5 generations.
|
|
|
|
### `GET /:id/descendants?generations=N`
|
|
Get a descendant tree. Default 3 generations.
|
|
|
|
### `POST /trial-pairing`
|
|
Calculate Coefficient of Inbreeding (COI) for a hypothetical mating.
|
|
- **Body**: `sire_id`, `dam_id`.
|
|
- **Response**: `{ coi, commonAncestors, directRelation, recommendation }`
|
|
|
|
---
|
|
|
|
## 7. Settings (`/api/settings`)
|
|
|
|
### `GET /`
|
|
Get kennel metadata (name, address, etc.).
|
|
|
|
### `PUT /`
|
|
Update kennel settings.
|
|
|
|
---
|
|
|
|
## Data Objects
|
|
|
|
### Dog Object
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"name": "BREEDR Champion",
|
|
"registration_number": "AKC123456",
|
|
"breed": "Golden Retriever",
|
|
"sex": "male",
|
|
"birth_date": "2020-01-01",
|
|
"color": "Golden",
|
|
"microchip": "900123456789",
|
|
"is_active": 1,
|
|
"is_champion": 1,
|
|
"is_external": 0,
|
|
"photo_urls": ["/uploads/img.jpg"],
|
|
"notes": "Excellent temperament",
|
|
"sire": { "id": 10, "name": "Sire Name" },
|
|
"dam": { "id": 11, "name": "Dam Name" }
|
|
}
|
|
```
|
|
|
|
### Litter Object
|
|
```json
|
|
{
|
|
"id": 5,
|
|
"sire_id": 1,
|
|
"dam_id": 2,
|
|
"breeding_date": "2023-01-01",
|
|
"whelp_date": "2023-03-05",
|
|
"total_count": 8,
|
|
"puppies": [ ... ]
|
|
}
|
|
```
|