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

[
    {
        "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

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

[
    {
        "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

[
    {
        "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