Breeding API endpoint

A breeding pair, the dam and the sire, with the litters it produced.

Table of contents

1. Endpoints
2. Fields
3. List
4. Add
5. Detail
6. Change
7. Delete
8. Data model
9. Usage notes

Endpoints

• Private portal: https://www.brainstem.org/api/private/stem/breeding/ (needs a token; one record: append <id>/)
• Public portal: https://www.brainstem.org/api/public/stem/breeding/ (read-only, public projects, no token)
• Response keys: breeding (detail, create, update), breedings (list)
• Permissions: inherited through project (from project)
• Uniqueness: name, project unique together
• Deleting: clears the link on subject records

Fields

[required] fields must be sent on create; [read-only] fields are returned but cannot be set. A nestable relation can be traversed in filters (filter{field.other}) and sideloaded with include[]=field.*; other relations can only be compared with ids (filter{field}=<id>). See the query syntax.

Field	Description
id	UUID string [read-only]
name	string [required]; max 100 characters
status	one of planned, performed, cancelled [required]. Planned: prepared but nothing has happened yet. Performed: this record describes what was done. Cancelled: planned and then dropped; kept for the record.
project	project id [required]
mother	subject id [required]
father	subject id [required]
description	string; nullable
tags	list of strings; filter with filter{tags.name}=<name>
birth_date	date; nullable. Date of birth of the offspring.
litter_size	number; nullable. Expected or actual number of offspring.
expected_genotype	string; max 100 characters; nullable. Expected genotype of the offspring.
weaning_date	date; nullable. Date the litter was or will be weaned (21-28 days after birth, typically; format: YYYY-MM-DD).
start_date	date; nullable. Date when this breeding started (pairing date; format: YYYY-MM-DD).
end_date	date; nullable. Date when this breeding ended (separation date; format: YYYY-MM-DD). Leave blank if ongoing.

List

• Allowed portals: private, public
• Request method: GET
• URL: https://www.brainstem.org/api/private/stem/breeding/
• Responses: 200 OK; 401 Not authenticated; 403 Not allowed

Use example (Python API tool)

resp = client.load('breeding', load_all=True)
records = resp['breedings']

Use example (MATLAB API tool)

resp = client.load('breeding', 'load_all', true);
records = resp.breedings;

Response example

{
    "breedings": [
        {
            "id": "<id>",
            "name": "Breeding 1",
            "status": "performed",
            "project": "<project-id>",
            "mother": "<subject-id>",
            "father": "<subject-id>",
            "description": "",
            "tags": [],
            "birth_date": "2024-03-22",
            "litter_size": 1,
            "expected_genotype": "",
            "weaning_date": "2024-03-22",
            "start_date": "2024-03-22",
            "end_date": "2024-03-22"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_results": 1,
        "total_pages": 1
    }
}

Add

• Allowed portals: private
• Request method: POST
• URL: https://www.brainstem.org/api/private/stem/breeding/
• Data: JSON object with at least the required fields
• Responses: 201 Created; 400 Bad request (validation errors per field); 403 Not allowed

Use example (Python API tool)

resp = client.save('breeding', data={"name": "Breeding 1", "status": "performed", "project": "<project-id>", "mother": "<subject-id>", "father": "<subject-id>"})
record = resp.json()['breeding']

Use example (MATLAB API tool)

created = client.save(struct('name', 'Breeding 1', 'status', 'performed', 'project', '<project-id>', 'mother', '<subject-id>', 'father', '<subject-id>'), 'breeding');
record = created.breeding;

Detail

• Allowed portals: private, public
• Request method: GET
• URL: https://www.brainstem.org/api/private/stem/breeding/<id>/
• Responses: 200 OK; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.load('breeding', id='<id>')
record = resp.json()['breeding']

Use example (MATLAB API tool)

out = client.load('breeding', 'id', '<id>');
record = out.breeding;

Response example

{
    "breeding": {
        "id": "<id>",
        "name": "Breeding 1",
        "status": "performed",
        "project": "<project-id>",
        "mother": "<subject-id>",
        "father": "<subject-id>",
        "description": "",
        "tags": [],
        "birth_date": "2024-03-22",
        "litter_size": 1,
        "expected_genotype": "",
        "weaning_date": "2024-03-22",
        "start_date": "2024-03-22",
        "end_date": "2024-03-22"
    }
}

Change

• Allowed portals: private
• Request method: PATCH
• URL: https://www.brainstem.org/api/private/stem/breeding/<id>/
• Data: JSON object with the fields to change. Lists (projects, tags, …) and JSON payloads (details, coordinates) are replaced as a whole: read the record first and send the full list or object.
• Responses: 200 OK; 400 Bad request; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.save('breeding', id='<id>', data={"name": "Breeding 1 (renamed)"})

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'Breeding 1 (renamed)'), 'breeding', 'method', 'patch');

Delete

• Allowed portals: private
• Request method: DELETE
• URL: https://www.brainstem.org/api/private/stem/breeding/<id>/
• Responses: 204 Deleted; 400 Still referenced by other records; 403 Not allowed; 404 Not found

Use example (Python API tool)

resp = client.delete('breeding', id='<id>')

Use example (MATLAB API tool)

client.delete('<id>', 'breeding');

Data model

The fields are described for the web forms on the Breeding data model page.

Usage notes

• Both mother and father must belong to the breeding’s project; otherwise the request is refused with 400.