Data storage API endpoint
Where session data lives, how it can be reached and how it is organized.
Table of contents
Endpoints
- Private portal:
https://www.brainstem.org/api/private/personal_attributes/datastorage/(needs a token; one record: append<id>/) - Public portal:
https://www.brainstem.org/api/public/personal_attributes/datastorage/(read-only, public projects, no token) - Response keys:
datastorage(detail, create, update),datastorages(list) - Permissions: object permissions on the record itself (member / manager / owner roles)
- Uniqueness:
nameunique across BrainSTEM - Deleting: also deletes the linked
datastoragegroupmembershipinvitation,datastoragemembershipinvitationrecords
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 |
location | string; max 100 characters; nullable. Location of the data storage, e.g., “Cabinet A”, “Computer B”, “Network storage C”. |
description | string; nullable |
is_public | boolean. Designates if the data storage is publicly available |
data_organization | JSON object; nullable. The data organization of the storage, e.g., Projects → Subjects → Sessions |
data_protocols | JSON object; nullable. Available data protocols for this storage location |
users | computed [read-only] |
groups | computed [read-only] |
List
- Allowed portals: private, public
- Request method: GET
- URL:
https://www.brainstem.org/api/private/personal_attributes/datastorage/ - Responses:
200OK;401Not authenticated;403Not allowed
Use example (Python API tool)
resp = client.load('datastorage', load_all=True)
records = resp['datastorages']
Use example (MATLAB API tool)
resp = client.load('datastorage', 'load_all', true);
records = resp.datastorages;
Response example
{
"datastorages": [
{
"id": "<id>",
"name": "Data storage 1",
"location": "",
"description": "",
"is_public": true,
"data_organization": {},
"data_protocols": {},
"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/personal_attributes/datastorage/ - 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('datastorage', data={"name": "Data storage 1"})
record = resp.json()['datastorage']
Use example (MATLAB API tool)
created = client.save(struct('name', 'Data storage 1'), 'datastorage');
record = created.datastorage;
Detail
- Allowed portals: private, public
- Request method: GET
- URL:
https://www.brainstem.org/api/private/personal_attributes/datastorage/<id>/ - Responses:
200OK;403Not allowed;404Not found
Use example (Python API tool)
resp = client.load('datastorage', id='<id>')
record = resp.json()['datastorage']
Use example (MATLAB API tool)
out = client.load('datastorage', 'id', '<id>');
record = out.datastorage;
Response example
{
"datastorage": {
"id": "<id>",
"name": "Data storage 1",
"location": "",
"description": "",
"is_public": true,
"data_organization": {},
"data_protocols": {},
"users": null,
"groups": null
}
}
Change
- Allowed portals: private
- Request method: PATCH
- URL:
https://www.brainstem.org/api/private/personal_attributes/datastorage/<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('datastorage', id='<id>', data={"name": "Data storage 1 (renamed)"})
Use example (MATLAB API tool)
client.save(struct('id', '<id>', 'name', 'Data storage 1 (renamed)'), 'datastorage', 'method', 'patch');
Delete
- Allowed portals: private
- Request method: DELETE
- URL:
https://www.brainstem.org/api/private/personal_attributes/datastorage/<id>/ - Responses:
204Deleted;400Still referenced by other records;403Not allowed;404Not found
Use example (Python API tool)
resp = client.delete('datastorage', id='<id>')
Use example (MATLAB API tool)
client.delete('<id>', 'datastorage');
Custom actions
| Action | Request |
|---|---|
filter_by_group | GET /api/private/personal_attributes/datastorage/filter_by_group/ |
leave | POST /api/private/personal_attributes/datastorage/<id>/leave/ |
JSON field schemas
Schemas for the data organization and access protocols of a data storage. 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/DataStorage/<Type>/<version>.json and never changes; see Public schemas.
Data organization
- type code
data_organization· version 1.0.0 · schema
Define the hierarchical organization of the data in this data storage, from top-level to most specific. Example: Projects → Subjects → Sessions.
This type has no type-specific properties: send an empty object. Everything meaningful is recorded on the record itself or on its material usage rows.
Data protocols
- type code
data_protocols· version 1.0.0 · schema
Define the available protocols for accessing this data storage. Each protocol specifies how users can connect to and retrieve data from the storage system. On your local system, you can further define a separate set of local access protocols if applicable.
| Property | Description |
|---|---|
protocol | Protocol Type: choice [required]; one of Globus, HTTPS/Web, SFTP, FTP, SMB/CIFS, NFS, AFP, S3, Dropbox, Google Drive, OneDrive, Local Storage, Other; default "HTTPS/Web" |
path | Access Path/URL: text [required] |
is_public | Public Access: yes/no; default false; format select |
Illustrative payload:
[
{
"protocol": "Globus",
"path": "text",
"is_public": false
}
]
Data model
The fields are described for the web forms on the Data storage data model page.