Project API endpoint
Groups the subjects, sessions and specimens of a study and sets who can see and edit them.
Table of contents
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:
nameunique across BrainSTEM - Deleting: also deletes the linked
breeding,cohort,collection,projectgroupmembershipinvitation,projectmembershipinvitationrecords
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 200 characters |
description | string; nullable |
sessions | list of session ids [read-only]; nullable; nestable |
subjects | list of subject ids [read-only]; nullable; nestable |
publications | list of publication ids |
extra_fields | JSON object |
is_public | boolean. Designates if the project is publicly available |
collections | list of collection ids [read-only]; nullable; nestable |
cohorts | list of cohort ids [read-only]; nullable; nestable |
tags | list of strings; filter with filter{tags.name}=<name> |
users | computed [read-only] |
groups | computed [read-only] |
List
- Allowed portals: private, public
- Request method: GET
- URL:
https://www.brainstem.org/api/private/stem/project/ - Responses:
200OK;401Not authenticated;403Not 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:
201Created;400Bad request (validation errors per field);403Not 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:
200OK;403Not allowed;404Not 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:
200OK;400Bad request;403Not allowed;404Not 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:
204Deleted;400Still referenced by other records;403Not allowed;404Not found
Use example (Python API tool)
resp = client.delete('project', id='<id>')
Use example (MATLAB API tool)
client.delete('<id>', 'project');
Custom actions
| Action | Request |
|---|---|
export | GET, POST /api/private/stem/project/<id>/export/ |
export_jobs | GET /api/private/stem/project/<id>/export-jobs/ |
export_job | GET /api/private/stem/project/<id>/export-jobs/<job_id>/ |
export_job_download | GET /api/private/stem/project/<id>/export-jobs/<job_id>/download/ |
leave | POST /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.
| Property | Description |
|---|---|
key | text |
value | object |
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.
| Property | Description |
|---|---|
repository | choice [required]; one of CRCNS, DANDI, Figshare, GitHub, Globus, Mendeley, Zenodo, Webshare, Other; default "DANDI" |
url | text [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
extra_fieldsis a JSON object whose keys start with a letter and contain only letters, digits and underscores; values are strings or numbers.usersandgroupsare read-only. To give a person or a group a role on the project, create a project membership invitation or a project group membership invitation. See Permissions for the roles.