Animal pedigree and family API

Base path through the gateway: /api/animal/v1/animals/{id}. Every route on this page is a GET, needs no bearer, and answers the platform envelope { data, resultCode } — resultCode values come from the Animal response-code category and the wire message is intentionally empty. This page is the reference. The service’s own OpenAPI document is for UPC platform staff only.

Two of these reads are page-shaped: they exist so a pedigree chart or a relationship table is one round trip, not one row read per box or per row. Use them for anything that renders a family; the graph reads underneath are for computing over the lineage (COI, kinship), not for listing it.

Pedigree chart — /{id}/pedigree

GET /api/animal/v1/animals/{id}/pedigree?generations=3

Parameter	Meaning
generations	Depth of the chart counting the subject: 3 (default) = parents + grandparents, up to 8.

{
  "animalId": "c55760cf-…",
  "generations": 3,
  "sireAnimalId": "b788c101-…",
  "damAnimalId": "406296d4-…",
  "ancestors": [
    {
      "animalId": "b788c101-…", "depth": 1, "rolePath": "1", "allGenetic": true,
      "upcCode": "CAD25HEIKO", "sexCode": "M",
      "callName": "Heiko vom Böhmershof", "callNameRomanized": null,
      "registeredName": null, "registeredNameRomanized": null,
      "sireAnimalId": "…", "damAnimalId": "…"
    }
  ]
}

• Every ancestor appears once, at its shortest line from the subject. rolePath is the >-joined parent roles along that line (1 = sire, 2 = dam; 1>2 = the sire’s dam).
• Rebuild the tree from sireAnimalId / damAnimalId, starting at the envelope’s own two ids, not from rolePath: a line-bred ancestor (the same dog behind both parents) is listed once but belongs in every position it holds, and following the ids places it there. Stop a branch at a null id (unknown / external parent) or at an id that is not in ancestors (beyond the requested depth).
• Names travel as both spellings of both names; pick the call name, then the registered name, then the UPC code, and show the romanization beside a non-Latin name.
• An animal with no recorded parents answers an empty ancestors array, not an error.

Family pages — /{id}/relatives

GET /api/animal/v1/animals/{id}/relatives?kind=OFFSPRING&skip=0&take=24

Parameter	Meaning
kind	SIBLINGS (shares at least one parent), OFFSPRING (direct children), EXTENDED (the parents’ siblings — uncles and aunts). Required.
skip, take	Paging; take 1–100, default 24.

{
  "kind": "OFFSPRING",
  "total": 1190,
  "skip": 0,
  "take": 24,
  "items": [
    {
      "animal": { "id": "…", "upcCode": "…", "callName": "A'Dreams CJ Adamia", "sexCode": "F", "dateOfBirth": "2019-03-02", "…": "…" },
      "siblingKind": null,
      "sire": { "animalId": "…", "callName": "Jivago v.h. Wantij", "…": "…" },
      "dam":  { "animalId": "…", "callName": "A'Dreams Coconut", "…": "…" }
    }
  ]
}

• total is the true family size even when the page is shorter; items are ordered oldest first (unknown birth dates last), then by name, so the same animal never lands on two pages.
• animal is the full animal record (the same shape as GET /animals/{id}); sire / dam are the row’s own parents as name references, so a table’s Sire / Dam columns need no further reads.
• siblingKind is FULL or HALF on SIBLINGS rows (both of the subject’s known parents shared, or one) and null otherwise.
• An unknown kind answers 400; an unknown animal 404; an animal without parents answers SIBLINGS / EXTENDED as an empty page with total: 0.

Graph reads

These walk the pedigree graph and return ids and depths only — no names.

Route	Returns
/{id}/ancestors?generations=8	every ancestor within N generations: animalId, depth, rolePath, allGenetic
/{id}/descendants?generations=8	every descendant within N generations, same shape
/{id}/coi?generations=8	shortest-path Coefficient-of-Inbreeding estimate: coiEstimate, contributingAncestorCount, bothParentsKnown (false ⇒ the estimate is meaningless and returned as 0)
/{id}/relatedness/{otherId}	kinship path distance and common-ancestor count between two animals
/{id}/common-ancestors/{otherId}	shared ancestors with the depth from each side
/{id}/littermate-suggestions?dobWindowDays=3&maxResults=50	likely littermates for an animal without a stored birth litter

generations on the graph reads is a maximum walk depth (1–20, default 8) and does not count the subject — unlike the pedigree chart’s parameter above.