Hardware device API endpoint

The shared catalogue of durable devices, such as amplifiers, cameras and lasers.

Table of contents

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

Endpoints

  • Private portal: https://www.brainstem.org/api/private/resources/hardwaredevice/ (needs a token; one record: append <id>/)
  • Public portal: https://www.brainstem.org/api/public/resources/hardwaredevice/ (read-only, public projects, no token)
  • Response keys: hardwaredevice (detail, create, update), hardwaredevices (list)
  • Permissions: see the permissions page
  • Uniqueness: name unique across BrainSTEM
  • Schema payload: type selects a HardwareDevice type; send its fields in type_json. type_schema_version is set by the server; do not send it.
  • Deleting: refused (400) while equipment records point to it

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
typeone of the HardwareDevice types [required]
descriptionstring; max 2000 characters
suppliersupplier id [required]
rridstring; max 100 characters; nullable. Research Resource Identifier (RRID) for tracking standardized research resources
rrid_urlstring [read-only]
type_jsonJSON object; nullable
external_identifiersJSON object; nullable. External identifiers and their source URLs from various databases (NCBI, JAX, DOI, etc.)
commentsstring

List

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

Use example (Python API tool)

resp = client.load('hardwaredevice', load_all=True)
records = resp['hardwaredevices']

Use example (MATLAB API tool)

resp = client.load('hardwaredevice', 'load_all', true);
records = resp.hardwaredevices;

Response example

{
    "hardwaredevices": [
        {
            "id": "<id>",
            "name": "Hardware device 1",
            "type": "Amplifier",
            "description": "",
            "supplier": "<supplier-id>",
            "rrid": "",
            "rrid_url": "",
            "type_json": {
                "...": "see the schema of the selected type"
            },
            "external_identifiers": {},
            "comments": ""
        }
    ],
    "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/resources/hardwaredevice/
  • 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('hardwaredevice', data={"name": "Hardware device 1", "type": "Amplifier", "supplier": "<supplier-id>", "type_json": {"...": "the fields of the selected HardwareDevice type"}})
record = resp.json()['hardwaredevice']

Use example (MATLAB API tool)

created = client.save(struct('name', 'Hardware device 1', 'type', 'Amplifier', 'supplier', '<supplier-id>', 'type_json', struct()), 'hardwaredevice');  % struct() stands for the fields of the selected type
record = created.hardwaredevice;

Detail

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Response example

{
    "hardwaredevice": {
        "id": "<id>",
        "name": "Hardware device 1",
        "type": "Amplifier",
        "description": "",
        "supplier": "<supplier-id>",
        "rrid": "",
        "rrid_url": "",
        "type_json": {
            "...": "see the schema of the selected type"
        },
        "external_identifiers": {},
        "comments": ""
    }
}

Change

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

Use example (MATLAB API tool)

client.save(struct('id', '<id>', 'name', 'Hardware device 1 (renamed)'), 'hardwaredevice', 'method', 'patch');

Delete

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

Use example (Python API tool)

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

Use example (MATLAB API tool)

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

Data model

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