Data storage API endpoint

Where session data lives, how it can be reached and how it is organized.

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. Data organization
    2. Data protocols
  10. Data model

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: name unique across BrainSTEM
  • Deleting: also deletes the linked datastoragegroupmembershipinvitation, datastoragemembershipinvitation 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 100 characters
locationstring; max 100 characters; nullable. Location of the data storage, e.g., “Cabinet A”, “Computer B”, “Network storage C”.
descriptionstring; nullable
is_publicboolean. Designates if the data storage is publicly available
data_organizationJSON object; nullable. The data organization of the storage, e.g., Projects → Subjects → Sessions
data_protocolsJSON object; nullable. Available data protocols for this storage location
userscomputed [read-only]
groupscomputed [read-only]

List

  • Allowed portals: private, public
  • Request method: GET
  • URL: https://www.brainstem.org/api/private/personal_attributes/datastorage/
  • Responses: 200 OK; 401 Not authenticated; 403 Not 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: 201 Created; 400 Bad request (validation errors per field); 403 Not 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: 200 OK; 403 Not allowed; 404 Not 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: 200 OK; 400 Bad request; 403 Not allowed; 404 Not 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: 204 Deleted; 400 Still referenced by other records; 403 Not allowed; 404 Not found

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Custom actions

ActionRequest
filter_by_groupGET /api/private/personal_attributes/datastorage/filter_by_group/
leavePOST /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.

PropertyDescription
protocolProtocol 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"
pathAccess Path/URL: text [required]
is_publicPublic 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.