Project API endpoint

Groups the subjects, sessions and specimens of a study and sets who can see and edit them.

Table of contents

  1. Endpoints
  2. Fields
  3. List
  4. Add
  5. Detail
  6. Change
  7. Delete
  8. Custom actions
  9. JSON field schemas
    1. Additional fields
    2. Public repositories
  10. Data model
  11. Usage notes

Endpoints

  • Private portal: https://www.brainstem.org/api/private/stem/project/ (needs a token; one record: append <id>/)
  • Public portal: https://www.brainstem.org/api/public/stem/project/ (read-only, public projects, no token)
  • Response keys: project (detail, create, update), projects (list)
  • Permissions: object permissions on the record itself (member / manager / owner roles)
  • Uniqueness: name unique across BrainSTEM
  • Deleting: also deletes the linked breeding, cohort, collection, projectgroupmembershipinvitation, projectmembershipinvitation 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.

FieldDescription
idUUID string [read-only]
namestring [required]; max 200 characters
descriptionstring; nullable
sessionslist of session ids [read-only]; nullable; nestable
subjectslist of subject ids [read-only]; nullable; nestable
publicationslist of publication ids
extra_fieldsJSON object
is_publicboolean. Designates if the project is publicly available
collectionslist of collection ids [read-only]; nullable; nestable
cohortslist of cohort ids [read-only]; nullable; nestable
tagslist of strings; filter with filter{tags.name}=<name>
userscomputed [read-only]
groupscomputed [read-only]

List

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

Use example (Python API tool)

resp = client.load('project', load_all=True)
records = resp['projects']

Use example (MATLAB API tool)

resp = client.load('project', 'load_all', true);
records = resp.projects;

Response example

{
    "projects": [
        {
            "id": "<id>",
            "name": "Project 1",
            "description": "",
            "sessions": [
                "<session-id>"
            ],
            "subjects": [
                "<subject-id>"
            ],
            "publications": [
                "<publication-id>"
            ],
            "extra_fields": {},
            "is_public": true,
            "collections": [
                "<collection-id>"
            ],
            "cohorts": [
                "<cohort-id>"
            ],
            "tags": [],
            "users": null,
            "groups": null
        }
    ],
    "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/project/
  • 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('project', data={"name": "Project 1"})
record = resp.json()['project']

Use example (MATLAB API tool)

created = client.save(struct('name', 'Project 1'), 'project');
record = created.project;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "project": {
        "id": "<id>",
        "name": "Project 1",
        "description": "",
        "sessions": [
            "<session-id>"
        ],
        "subjects": [
            "<subject-id>"
        ],
        "publications": [
            "<publication-id>"
        ],
        "extra_fields": {},
        "is_public": true,
        "collections": [
            "<collection-id>"
        ],
        "cohorts": [
            "<cohort-id>"
        ],
        "tags": [],
        "users": null,
        "groups": null
    }
}

Change

  • Allowed portals: private
  • Request method: PATCH
  • URL: https://www.brainstem.org/api/private/stem/project/<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('project', id='<id>', data={"name": "Project 1 (renamed)"})

Use example (MATLAB API tool)

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

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Custom actions

ActionRequest
exportGET, POST /api/private/stem/project/<id>/export/
export_jobsGET /api/private/stem/project/<id>/export-jobs/
export_jobGET /api/private/stem/project/<id>/export-jobs/<job_id>/
export_job_downloadGET /api/private/stem/project/<id>/export-jobs/<job_id>/download/
leavePOST /api/private/stem/project/<id>/leave/

export returns the project as versioned JSON (see Exports); POST starts a background export job, export-jobs lists your jobs for the project and export-jobs/<job_id>/download/ fetches the finished file.

JSON field schemas

Schemas for the additional fields and repository links of a project. The REST API returns these JSON fields as stored and validates writes against the schemas below. Every version is published at https://www.brainstem.org/schemas/Project/<Type>/<version>.json and never changes; see Public schemas.

Additional fields

  • type code Array · version 1.0.1 · schema

Any extra parameters you want to add to this project. Saved as key-value pairs. Values can be strings or numbers.

PropertyDescription
keytext
valueobject

Illustrative payload:

[
    {
        "key": "text",
        "value": {}
    }
]

Public repositories

  • type code Repository · version 1.0.0 · schema

Link to public repositories where data from this project is stored.

PropertyDescription
repositorychoice [required]; one of CRCNS, DANDI, Figshare, GitHub, Globus, Mendeley, Zenodo, Webshare, Other; default "DANDI"
urltext [required]; format url

Illustrative payload:

[
    {
        "repository": "CRCNS",
        "url": "text"
    }
]

Data model

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

Usage notes