HTTP API¶

Authentication¶

The iffSamples HTTP API uses Basic Authentication using the normal user credentials. 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.

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:

200 OK – no error

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:

302 Found – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object/version combination does not exist

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:

201 Created – no error
400 Bad Request – invalid data

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:

201 Created – no error
400 Bad Request – invalid data
403 Forbidden – the user does not have WRITE permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have GRANT permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object or user does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object or group does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object or project does not exist

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:

200 OK – no error

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:

200 OK – no error
404 Not Found – the instrument does not exist

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:

200 OK – no error

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:

200 OK – no error
404 Not Found – the action does not exist

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:

200 OK – no error

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:

200 OK – no error
404 Not Found – the user does not exist

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:

200 OK – no error

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:

200 OK – no error
404 Not Found – the location does not exist

Reading a list of an object’s locations¶

GET /api/v1/object/(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:

200 OK – no error

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/object/(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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object does not exist

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:

200 OK – no error
403 Forbidden – the user does not have READ permissions for this object
404 Not Found – the object or the file does not exist

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:

201 Created – the file has been created successfully
403 Forbidden – the user does not have WRITE permissions for this object
404 Not Found – the object does not exist

Posting a link¶

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

Create a new file with url 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": "url",
    "url": "https://iffsamples.fz-juelich.de"
}

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 (url)
url (string) – the URL of the file

Status Codes:

201 Created – the file has been created successfully
403 Forbidden – the user does not have WRITE permissions for this object
404 Not Found – the object does not exist