HTTP API

Authentication

The SampleDB HTTP API either uses Basic Authentication using normal user credentials (e.g. using the header Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=) or Bearer Authentication using the API token (e.g. using the header Authorization: Bearer bf4e16afa966f19b92f5e63062bd599e5f931faeeb604bdc3e6189539258b155). API tokens are meant as an alternative method for authentication for individual scripts and allow you to monitor the requests made with the token. You can create an API token when editing your Preferences.

Please make sure to use HTTPS when accessing the API.

Objects

Reading a list of all objects

GET /api/v1/objects/

Get a list of all objects visible to the current user.

The list only contains the current version of each object. By passing the parameter q to the query, the Advanced Search can be used. By passing the parameters action_id or action_type objects can be filtered by the action they were created with or by their type (e.g. sample or measurement).

Example request:

GET /api/v1/objects/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "object_id": 1,
        "version_id": 0,
        "action_id": 0,
        "schema": {
            "title": "Object Information",
            "type": "object",
            "properties": {
                "name": {
                    "title": "Object Name",
                    "type": "text"
                }
            }
        },
        "data": {
            "name": {
                "_type": "text",
                "text": "Example Object"
            }
        }
    },
    {
        "object_id": 2,
        "version_id": 3,
        "action_id": 0,
        "schema": {
            "title": "Object Information",
            "type": "object",
            "properties": {
                "name": {
                    "title": "Object Name",
                    "type": "text"
                }
            }
        },
        "data": {
            "name": {
                "_type": "text",
                "text": "Other Object"
            }
        }
    }
]
Status Codes:

Getting the current object version

GET /api/v1/objects/(int: object_id)

Redirect to the current version of an object (object_id).

Example request:

GET /api/v1/objects/1 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 302 Found
Location: /api/v1/objects/1/versions/0
Status Codes:

Reading an object version

GET /api/v1/objects/(int: object_id)/versions/(int: version_id)

Get the specific version (version_id) of an object (object_id).

Example request:

GET /api/v1/objects/1/versions/0 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "object_id": 1,
    "version_id": 0,
    "action_id": 0,
    "schema": {
        "title": "Object Information",
        "type": "object",
        "properties": {
            "name": {
                "title": "Object Name",
                "type": "text"
            }
        }
    },
    "data": {
        "name": {
            "_type": "text",
            "text": "Example Object"
        }
    }
}
Response JSON Object:

  • object_id (number) – the object’s ID

  • version_id (number) – the object version’s ID

  • action_id (number) – the action’s ID

  • schema (object) – the object’s schema

  • data (object) – the object’s data

Status Codes:

Creating a new object

POST /api/v1/objects/

Create a new object.

Example request:

POST /api/v1/objects/1/versions/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Content-Type: application/json
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
    "action_id": 0,
    "schema": {
        "title": "Object Information",
        "type": "object",
        "properties": {
            "name": {
                "title": "Object Name",
                "type": "text"
            }
        }
    },
    "data": {
        "name": {
            "_type": "text",
            "text": "Example Object"
        }
    }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/objects/1/versions/0
Request JSON Object:

  • version_id (number) – the object version’s ID (optional, must be 0)

  • action_id (number) – the action’s ID

  • schema (object) – the object’s schema (optional, must equal current action’s schema)

  • data (object) – the object’s data

Status Codes:

Updating an object / Creating a new object version

POST /api/v1/objects/(int: object_id)/versions/

Create a new version of an object (object_id).

Example request:

POST /api/v1/objects/1/versions/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Content-Type: application/json
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
    "data": {
        "name": {
            "_type": "text",
            "text": "Example Object"
        }
    }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/objects/1/versions/1
Request JSON Object:

  • object_id (number) – the object’s ID (optional, must equal object_id in URL)

  • version_id (number) – the object version’s ID (optional, must equal new version’s ID)

  • action_id (number) – the action’s ID (optional, must equal previous action_id)

  • schema (object) – the object’s schema (optional, must equal previous schema or current action’s schema)

  • data (object) – the object’s data

Status Codes:

Object Permissions

Reading whether an object is public

GET /api/v1/objects/(int: object_id)/permissions/public

Get whether or not an object is public.

Example request:

GET /api/v1/objects/1/permissions/public HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

true
Status Codes:

Setting whether an object is public

PUT /api/v1/objects/(int: object_id)/permissions/public

Get whether or not an object is public.

Example request:

PUT /api/v1/objects/1/permissions/public HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

false

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

false
Status Codes:

Reading all users’ permissions

GET /api/v1/objects/(int: object_id)/permissions/users/

Get a mapping of user IDs to their permissions.

Example request:

GET /api/v1/objects/1/permissions/users/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "1": "read",
    "2": "grant"
}
Query Parameters:

  • include_instrument_responsible_users – If given, permissions from being an instrument responsible user will be included (optional)

  • include_groups – If given, permissions from group memberships will be included (optional)

  • include_projects – If given, permissions from project memberships will be included (optional)

Status Codes:

Reading a user’s permissions

GET /api/v1/objects/(int: object_id)/permissions/users/(int: user_id)

Get the permissions of a user for an object.

Example request:

GET /api/v1/objects/1/permissions/users/2 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"grant"
Query Parameters:

  • include_instrument_responsible_users – If given, permissions from being an instrument responsible user will be included (optional)

  • include_groups – If given, permissions from group memberships will be included (optional)

  • include_projects – If given, permissions from project memberships will be included (optional)

Status Codes:

Setting a user’s permissions

PUT /api/v1/objects/(int: object_id)/permissions/users/(int: user_id)

Set the permissions of a user for an object.

Example request:

PUT /api/v1/objects/1/permissions/users/2 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

"write"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"write"
Status Codes:

  • 200 OK – no error

  • 400 Bad Request – invalid data (should be “read”, “write”, “grant” or “none”)

  • 403 Forbidden – the user does not have GRANT permissions for this object

  • 404 Not Found – the object or user does not exist

Reading all groups’ permissions

GET /api/v1/objects/(int: object_id)/permissions/groups/

Get a mapping of group IDs to their permissions.

Example request:

GET /api/v1/objects/1/permissions/groups/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "4": "write"
}
Query Parameters:

  • include_projects – If given, permissions from project memberships will be included (optional)

Status Codes:

Reading a group’s permissions

GET /api/v1/objects/(int: object_id)/permissions/groups/(int: group_id)

Get the permissions of a group for an object.

Example request:

GET /api/v1/objects/1/permissions/groups/4 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"write"
Query Parameters:

  • include_projects – If given, permissions from project memberships will be included (optional)

Status Codes:

Setting a group’s permissions

PUT /api/v1/objects/(int: object_id)/permissions/groups/(int: group_id)

Set the permissions of a group for an object.

Example request:

PUT /api/v1/objects/1/permissions/groups/2 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

"read"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"read"
Status Codes:

  • 200 OK – no error

  • 400 Bad Request – invalid data (should be “read”, “write”, “grant” or “none”)

  • 403 Forbidden – the user does not have GRANT permissions for this object

  • 404 Not Found – the object or group does not exist

Reading all projects’ permissions

GET /api/v1/objects/(int: object_id)/permissions/projects/

Get a mapping of project IDs to their permissions.

Example request:

GET /api/v1/objects/1/permissions/projects/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "7": "read"
}
Status Codes:

Reading a project’s permissions

GET /api/v1/objects/(int: object_id)/permissions/projects/(int: project_id)

Get the permissions of a project for an object.

Example request:

GET /api/v1/objects/1/permissions/projects/7 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"read"
Status Codes:

Setting a project’s permissions

PUT /api/v1/objects/(int: object_id)/permissions/projects/(int: project_id)

Set the permissions of a project for an object.

Example request:

PUT /api/v1/objects/1/permissions/projects/2 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

"read"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"read"
Status Codes:

  • 200 OK – no error

  • 400 Bad Request – invalid data (should be “read”, “write”, “grant” or “none”)

  • 403 Forbidden – the user does not have GRANT permissions for this object

  • 404 Not Found – the object or project does not exist

Instruments

Reading a list of all instruments

GET /api/v1/instruments/

Get a list of all instruments.

Example request:

GET /api/v1/instruments/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "instrument_id": 1,
        "name": "Example Instrument",
        "description": "This is an example instrument",
        "instrument_scientists": [1, 42]
    }
]
Status Codes:

Reading an instrument

GET /api/v1/instruments/(int: instrument_id)

Get the specific instrument (instrument_id).

Example request:

GET /api/v1/instruments/1 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "instrument_id": 1,
    "name": "Example Instrument",
    "description": "This is an example instrument",
    "instrument_scientists": [1, 42]
}
Response JSON Object:

  • instrument_id (number) – the instrument’s ID

  • name (string) – the instruments’s name

  • description (string) – the instruments’s description

  • instrument_scientists (list) – the instrument scientists’ IDs

Status Codes:

Actions

Reading a list of all actions

GET /api/v1/actions/

Get a list of all actions.

Example request:

GET /api/v1/actions/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "action_id": 1,
        "instrument_id": null,
        "type": "sample",
        "name": "Example Sample Creation",
        "description": "This is an example action",
        "schema": {
            "title": "Example Sample",
            "type": "object",
            "properties": {
                "name": {
                    "title": "Sample Name",
                    "type": "text"
                }
            },
            "required": ["name"]
        }
    },
    {
        "action_id": 2,
        "instrument_id": 1,
        "type": "measurement",
        "name": "Example Measurement",
        "description": "This is an example action",
        "schema": {
            "title": "Example Measurement",
            "type": "object",
            "properties": {
                "name": {
                    "title": "Measurement Name",
                    "type": "text"
                }
            },
            "required": ["name"]
        }
    }
]
Status Codes:

Reading an action

GET /api/v1/actions/(int: action_id)

Get the specific action (action_id).

Example request:

GET /api/v1/actions/1 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "action_id": 1,
    "instrument_id": null,
    "type": "sample",
    "name": "Example Sample Creation",
    "description": "This is an example action",
    "schema": {
        "title": "Example Sample",
        "type": "object",
        "properties": {
            "name": {
                "title": "Sample Name",
                "type": "text"
            }
        },
        "required": ["name"]
    }
}
Response JSON Object:

  • action_id (number) – the action’s ID

  • instrument_id (number) – the actions’s instrument’s ID or null

  • type (string) – the action’s type (“sample”, “measurement” or “simulation”)

  • name (string) – the actions’s name

  • description (string) – the actions’s description

  • schema (object) – the actions’s schema

Status Codes:

Users

Reading a list of all users

GET /api/v1/users/

Get a list of all users.

Example request:

GET /api/v1/users/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "user_id": 1,
        "name": "Example User"
    }
]
Status Codes:

Reading a user

GET /api/v1/users/(int: user_id)

Get the specific user (user_id).

Example request:

GET /api/v1/users/1 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_id": 1,
    "name": "Example User"
}
Response JSON Object:

  • user_id (number) – the user’s ID

  • name (string) – the user’s name

Status Codes:

Reading the current user

GET /api/v1/users/me

Get the current user.

Example request:

GET /api/v1/users/me HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_id": 1,
    "name": "Example User"
}
Response JSON Object:

  • user_id (number) – the user’s ID

  • name (string) – the user’s name

Status Codes:

Locations

Reading a list of all locations

GET /api/v1/locations/

Get a list of all locations.

Example request:

GET /api/v1/locations/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "location_id": 1,
        "name": "Example Location",
        "description": "This is an example location",
        "parent_location_id": null
    }
]
Status Codes:

Reading a location

GET /api/v1/locations/(int: location_id)

Get the specific location (location_id).

Example request:

GET /api/v1/locations/1 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "location_id": 1,
    "name": "Example Location",
    "description": "This is an example location",
    "parent_location_id": null
}
Response JSON Object:

  • location_id (number) – the location’s ID

  • name (string) – the locations’s name

  • description (string) – the locations’s description

  • parent_location_id (number) – the parent location’s ID

Status Codes:

Reading a list of an object’s locations

GET /api/v1/objects/(int: object_id)/locations/

Get a list of all object locations assignments for a specific object (object_id).

Example request:

GET /api/v1/objects/1/locations/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "object_id": 1,
        "location_id": 3,
        "responsible_user_id": 6,
        "user_id": 17,
        "description": "Shelf C",
        "utc_datetime": "2018-12-11 17:50:00"
    }
]
Status Codes:

Reading an object’s location

GET /api/v1/objects/(int: object_id)/locations/(int: index)

Get a specific object location assignment (index) for a specific object (object_id).

Example request:

GET /api/v1/objects/1/locations/0 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "object_id": 1,
    "location_id": 3,
    "responsible_user_id": 6,
    "user_id": 17,
    "description": "Shelf C",
    "utc_datetime": "2018-12-11 17:50:00"
}
Response JSON Object:

  • object_id (number) – the object’s ID

  • location_id (number) – the location’s ID

  • responsible_user_id (number) – the ID of the user who is responsible for the object

  • user_id (number) – the ID of the user who assigned this location to the object

  • description (string) – the description of the object’s position

  • utc_datetime (number) – the datetime when the object was stored

Status Codes:

  • 200 OK – no error

  • 404 Not Found – the object or the object location assignment does not exist

Files

Reading a list of an object’s files

GET /api/v1/objects/(int: object_id)/files/

Get a list of all files for a specific object (object_id).

Example request:

GET /api/v1/objects/1/files/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "object_id": 1,
        "file_id": 0,
        "storage": "url",
        "url": "https://iffsamples.fz-juelich.de"
    }
]
Status Codes:

Reading information for a file

GET /api/v1/objects/(int: object_id)/files/(int: file_id)

Get a specific file (file_id) for a specific object (object_id).

Example request:

GET /api/v1/objects/1/files/0 HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "object_id": 1,
    "file_id": 0,
    "storage": "url",
    "url": "https://iffsamples.fz-juelich.de"
}
Response JSON Object:

  • object_id (number) – the object’s ID

  • file_id (number) – the file’s ID

  • storage (string) – how the file is stored (local or url)

  • url (string) – the URL of the file (for url storage)

  • original_file_name (string) – the original name of the file (for local storage)

  • base64_content (string) – the base64 encoded content of the file (for local storage)

Status Codes:

Uploading a file

POST /api/v1/objects/(int: object_id)/files/

Create a new file with local storage for a specific object (object_id).

Example request:

POST /api/v1/objects/1/files/ HTTP/1.1
Host: iffsamples.fz-juelich.de
Accept: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
    "storage": "local",
    "original_file_name": "test.txt",
    "base64_content": "dGVzdA=="
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://iffsamples.fz-juelich.de/api/v1/objects/1/files/0
Request JSON Object:

  • storage (string) – how the file is stored (local)

  • original_file_name (string) – the original name of the file

  • base64_content (string) – the base64 encoded content of the file

Status Codes: