NAV Navbar
shell

Introduction

Welcome to the Open Interop Core API! You can use our API to access Open Interop Core API endpoints, which can get information on various information in the platform. The API is also what the interface within the application uses in order to manage the interoperability layer.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Before being able to use the system you will need to login with the username and password given to you (either by your manager or through signing up).

Use the authentication token retrieved with the Login call below.

Login

curl --location --request POST 'http://localhost/api/v1/auth/login' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "email": "your_email_address",
    "password": "your_password"
}'

On Success it will return:

{
    "token": "eyJhbGciOiJIUzI1NiJ9.byJ1c2VyX2lkIjozMywiZXhwIsoxNTg3NTz1MDc3fQ.z44g3zSXGZkZDwa1iW4NgC7Bd_GSxiz3qCpNu5jYDiQ",
    "exp": "04-20-2020 09:44",
    "email": "bob.testing@testing.co.uk"
}

HTTP Request

POST http://localhost/api/v1/auth/login

Content Body

Json string containing: { "email":"your_email_address", "password":"your_password" }

Dashboard

The Dashboard is where summary information would be gathered from

Transmissions Status

HTTP Request

GET http://localhost/api/v1/dashboards/transmissions?group=status

URL Parameters

Parameter Description
group status

Headers

Parameter Description
Authorization yourauthtoken
curl "http://localhost/api/v1/dashboards/transmissions?group=status"
  -H "Authorization: yourauthtoken"

Password

Request Password Reset

curl --location --request POST 'http://localhost/api/v1/passwords' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "email": "your_email_address"
}'

If you have forgotten your password then you can request a token to allow it to be reset.

HTTP Request

POST http://localhost/api/v1/passwords

Content Body

Json string containing: { "email":"your_email_address" }

Reset password

curl --location --request POST 'http://localhost/api/v1/passwords/reset' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "token": "your_password_reset_token",
  "password" : "newpassword",
  "password_confirmation" : "newpassword"
}'

Once you have the reset password token (from above), then you can send though an updated password along with a confirmation copy of it.

HTTP Request

POST http://localhost/api/v1/passwords/reset

Headers

Parameter Description
token your_password_reset_token
password your_new_password_string
password_confirmation your_new_password_string

Users

Users are made up of the following fields... (and other words)

The Site can have one or more of the following fields:

Field Type Required Notes
id number yes Unique
email string yes Unique
time_zone string no Default en-gb
password string yes only accessed via API calls

Filters available:

Filter Type
id number
email string
time_zone string
sort[field] string as above (excluding password)
sort[direction] string

Create a New User

curl --location --request POST 'http://localhost/api/v1/users' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
"user" : {
  "email": "new_email_address",
  "password": "new_password",
  "password_confirmation": "new_password"
}}'

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 2
}

HTTP Request

POST http://localhost/api/v1/users

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "email":"new_email_address", "password":"new_password", "password_confirmation":"new_password", }

Get User

curl --location --request GET 'http://localhost/api/v1/users/666' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

On Success:

    {
        "id": 666,
        "email": "testperson1@testplace.com",
        "created_at": "2019-12-13T16:30:56.104Z",
        "updated_at": "2020-04-14T09:43:33.425Z",
        "time_zone": "Mexico City"
    },

Get details for a single user on the system.

HTTP Request

GET http://localhost/api/v1/users/<id>

URL Parameter

Parameter Description
id User ID

Headers

Parameter Description
Authorization yourauthtoken

List Users

curl --location --request GET 'http://localhost/api/v1/users' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

On Success the command returns JSON structured like this:

{
    "total_records": 2,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 666,
            "email": "testperson1@testplace.com",
            "created_at": "2019-12-13T16:30:56.104Z",
            "updated_at": "2020-04-14T09:43:33.425Z"
        },
        {...}
    ],
    "core_version": "1.1.4"
}

Gets a list of the users on the system.

HTTP Request

GET http://localhost/api/v1/users

URL Parameter

Parameter Description
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Delete a User

curl --location --request DELETE 'http://localhost/api/v1/users/666' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

Delete a single user from the system.

HTTP Request

DELETE http://localhost/api/v1/users/<id>

URL Parameter

Parameter Description
id User ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

Update a User

curl --location --request PUT 'http://localhost/api/v1/users/666' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'  \
--data-raw '{ "user" : { "time_zone" : "Bern" } }'

Update details for a single user on the system.

HTTP Request

PUT http://localhost/api/v1/users/<id>

URL Parameter

Parameter Description
id User ID to be updated

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "user": { "time_zone":"Bern", } }

Sites

Sites are made up of the following fields.

The Site can have one or more of the following fields:

Field Type Required Sortable
id number yes yes
account_id number yes yes
site_id number no yes
name string no yes
description string no yes
address string no yes
city string no yes
state string no yes
zip_code string no yes
country string no yes
region string no yes
latitude number no no
longitude number no no
time_zone string no yes
external_uuids object no no
full_name string no yes

Filters available:

Filter Type
id number
account_id number
site_id number
latitude number
longitude number
name string
full_name string
description string
address string
city string
state string
zip_code string
country string
region string
time_zone string
sort[field] string as above (where marked as sortable)
sort[direction] string

Create a New Site

curl --location --request POST 'http://localhost/api/v1/sites' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{ "site" : { "name" : "XYZABC", "account_id" : 22 } }'

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 88,
  "account_id": 22,
  "site_id": null,
  "name": "XYZABC",
  "description": null,
  "address": null,
  "city": null,
  "state": null,
  "zip_code": null,
  "country": null,
  "region": null,
  "latitude": null,
  "longitude": null,
  "time_zone": null,
  "external_uuids": {},
  "created_at": "2020-04-14T16:28:08.984Z",
  "updated_at": "2020-04-14T16:28:09.025Z",
  "full_name": "XYZABC"
}

HTTP Request

POST http://localhost/api/v1/sites

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "site" : { "name" : "XYZABC", "account_id" : 22 } }

List Sites

curl --location --request GET 'http://localhost/api/v1/sites' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

On Success the command returns JSON structured like this:

{
    "total_records": 2,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 88,
            "account_id": 22,
            "site_id": null,
            "name": "XYZABC",
            "full_name": "XYZABC",
            "description": null,
            "address": null,
            "city": null,
            "state": null,
            "zip_code": null,
            "country": null,
            "region": null,
            "latitude": null,
            "longitude": null,
            "time_zone": null,
            "external_uuids": {},
            "created_at": "2020-04-14T16:28:08.984Z",
            "updated_at": "2020-04-14T16:28:09.025Z"
        },
        {...}
    ],
    "core_version": "1.1.4"
}

Gets a list of the sites on the system.

HTTP Request

GET http://localhost/api/v1/sites

URL Parameter

Parameter Description
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Delete a Site

curl --location --request DELETE 'http://localhost/api/v1/sites/666' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

Delete a single site from the system.

HTTP Request

DELETE http://localhost/api/v1/sites/<id>

URL Parameter

Parameter Description
id Site ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

Update a Site

curl --location --request PUT 'http://localhost/api/v1/sites/666' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'  \
--data-raw '{ "site" : { "name" : "QWERTY" } }'

Update details for a single site on the system.

HTTP Request

PUT http://localhost/api/v1/sites/<id>

URL Parameter

Parameter Description
id Site ID to be updated

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "site": { "name":"QWERTY", } }

History

curl --location --request GET 'http://localhost/api/v1/sites/666/history' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

Get the History Audit information for a single Site on the system.

HTTP Request

PUT http://localhost/api/v1/sites/<id>/history

URL Parameter

Parameter Description
id Site ID to be updated

Headers

Parameter Description
Authorization yourauthtoken
curl --location --request GET 'http://localhost/api/v1/sites/sidebar?site_id=666' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

On Success it Returns:

{
    "sites": [
        {
            "id": 666,
            "name": "Test Account Site",
            "device_groups": [
                {
                    "id": 56,
                    "name": "Test Account Device Group",
                    "devices": [
                        {
                            "id": 42,
                            "name": "Test Account Device"
                        },
                        {
                            "id": 23,
                            "name": "AnotherTestDevice"
                        }
                    ]
                },
                {
                    "id": 78,
                    "name": "XYZ-Capture devices",
                    "devices": []
                }
            ]
        },
        {
        ...
        }
    ]
}

The sidebar endpoint is purely used to render the sidebar in the interface. It groups devices together under their device groups, and the site they belong to.

HTTP Request

To get ALL sites:

PUT http://localhost/api/v1/sites/sidebar

For a specific site:

PUT http://localhost/api/v1/sites/sidebar?site_id=5

URL Parameter

Parameter Description
site_id (optional) Site ID to get sidebar for

Headers

Parameter Description
Authorization yourauthtoken

Device Groups

The Device Group can have one or more of the following fields:

Field Type Required Notes
id number yes Unique
name string yes readable

Filters available:

Filter Type
id number
name string
sort[field] string as above
sort[direction] string

Create a New Device Group

curl --location --request POST 'http://localhost/api/v1/device_groups' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{ "device_group" : { "name" : "XYZ_ABC", "description" : "Test of XYZ Connector" } }'

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 88
}

HTTP Request

POST http://localhost/api/v1/device_groups

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "device_group" : { "name" : "XYZ_ABC", "description" : "Test of XYZ Connector" } }

List

curl --location --request GET 'http://localhost/api/v1/device_groups' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 2,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 16,
            "name": "ABC-Capture devices",
            "created_at": "2019-10-25T14:24:50.649Z",
            "updated_at": "2019-10-25T14:24:50.649Z"
        },
        {
            "id": 1,
            "name": "XYZ Device Group",
            "created_at": "2019-08-30T08:58:48.022Z",
            "updated_at": "2019-08-30T08:58:48.022Z"
        }
    ],
    "core_version": "1.1.4"
}

This command will list existing device groups.

HTTP Request

GET http://localhost/api/v1/device_groups

URL Parameter

Parameter Description
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Update

curl --location --request PUT 'http://localhost/api/v1/device_groups/4' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain' \
--data-raw '{ "user" : { "time_zone" : "London" } }'

On Success the command will return:

This command will update specified fields within a device group.

HTTP Request

PUT http://localhost/api/v1/device_groups/<id>

URL Parameter

Parameter Description
id device group ID to be updated

Content Body

Json string containing: { "xxx": { "name":"QWERTY", } }

Headers

Parameter Description
Authorization yourauthtoken

Delete

Delete a single device group from the system.

HTTP Request

DELETE http://localhost/api/v1/device_groups/<id>

URL Parameter

Parameter Description
id device group ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

History

curl --location --request GET 'http://localhost/api/v1/device_groups/1/history' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 0,
    "number_of_pages": 0,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [],
    "core_version": "1.1.4"
}

This command will get the audit history for the specified device group.

HTTP Request

GET http://localhost/api/v1/device_groups/<id>/history

URL Parameter

Parameter Description
id device group ID to get history for

Headers

Parameter Description
Authorization yourauthtoken

Schedules

Timings are Cron style timing definitions "/x" = runs every x minor time units, "x" = run on x minor time units after the major time until eg. for minute "12/2" will run the task every 2 minutes after 12

Schedules have these fields:

Fieldname Type Info Sortable
id number Unique ID yes
name string Readable name yes
minute string Timing string see above no
hour string Timing string see above no
day_of_week string Timing string see above no
day_of_month string Timing string see above no
month_of_year string Timing string see above no
year string Timing string see above no
active bool true or false yes

Filters available:

Filter Type
id number
name string
active string
sort[field] string as above (where marked as sortable)
sort[direction] string

Create

curl --location --request POST 'http://localhost/api/v1/schedules' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "schedule" : {
    "name" : "XYZ_Schedule",
    "day_of_week" : "1"
  }
}'

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 88,
  "account_id": 1,
  "name": "XYZ_Schedule",
  "active": true,
  "minute": "*",
  "hour": "*",
  "day_of_week": "1",
  "day_of_month": "*",
  "month_of_year": "*",
  "year": "*",
  "created_at": "2020-04-22T15:12:08.260Z",
  "updated_at": "2020-04-22T15:12:08.260Z"
}

HTTP Request

POST http://localhost/api/v1/schedules

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "schedule" : { "name" : "XYZ_Schedule", "day_of_week" : "1" } }

List

curl --location --request GET 'http://localhost/api/v1/schedules' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
      {
        "id": 1,
        "name": "XYZ_Schedule",
        "minute": "*/2",
        "hour": "*",
        "day_of_week": "*",
        "day_of_month": "*",
        "month_of_year": "*",
        "year": "*",
        "created_at": "2020-02-03T17:03:02.185Z",
        "updated_at": "2020-02-05T18:21:41.830Z",
        "active": true
      }
    ],
    "core_version": "1.1.4"
}

This command will fetch a list of schedules based in the filters supplied, or all of them if no filters given.

HTTP Request

GET http://localhost/api/v1/schedules

URL Parameter

Parameter Description
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Update

curl --location --request PUT 'http://localhost/api/v1/schedules/1' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain' \
--data-raw '{ "schedule" : { "active" : false } }'

On Success the command will return:

{
    "account_id": 1,
    "id": 2,
    "active": false,
    "name": "XYZ_Schedule",
    "minute": "*",
    "hour": "*",
    "day_of_week": "1",
    "day_of_month": "*",
    "month_of_year": "*",
    "year": "*",
    "created_at": "2020-04-22T15:12:08.260Z",
    "updated_at": "2020-04-22T15:17:03.251Z"
}

This command will update the schedule for the supplied fields.

HTTP Request

PUT http://localhost/api/v1/schedules/<id>

URL Parameter

Parameter Description
id schedule ID to be updated

Content Body

Json string containing: { "schedule": { "active": false, } }

Headers

Parameter Description
Authorization yourauthtoken

Delete

curl --location --request DELETE 'http://localhost/api/v1/schedules/16' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken'

Delete a single schedule from the system.

HTTP Request

DELETE http://localhost/api/v1/schedules/<id>

URL Parameter

Parameter Description
id schedule ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

History

curl --location --request GET 'http://localhost/api/v1/schedules/2/history' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 410,
            "auditable_id": 2,
            "auditable_type": "Schedule",
            "associated_id": null,
            "associated_type": null,
            "user_id": 33,
            "user_type": "User",
            "username": null,
            "action": "create",
            "audited_changes": {
                "hour": "*",
                "name": "XYZ_Schedule",
                "year": "*",
                "active": true,
                "minute": "*",
                "account_id": 1,
                "day_of_week": "1",
                "day_of_month": "*",
                "month_of_year": "*"
            },
            "version": 1,
            "comment": null,
            "remote_address": "127.0.0.1",
            "request_uuid": "8f78e130-d7a3-4fbf-b6ac-b101b051bf37",
            "created_at": "2020-04-22T15:12:10.045Z"
        }
    ],
    "core_version": "1.1.4"
}

This command will ...

HTTP Request

GET http://localhost/api/v1/schedules/<id>/history

URL Parameter

Parameter Description
id schedule ID to get history for

Headers

Parameter Description
Authorization yourauthtoken

Assign Tempr to Schedule

curl --location --request POST 'http://localhost/api/v1/schedules/10/assign_tempr?tempr_id=5' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--data-raw ''

On Success the command will return:

This command will link a Tempr to a given Schedule.

HTTP Request

GET http://localhost/api/v1/schedules/<id>/assign_tempr?tempr_id=<tid>

URL Parameter

Parameter Description
id Schedule ID to assign to
tid Tempr ID to assign

Headers

Parameter Description
Authorization yourauthtoken

Devices

The Device can have one or more of the following fields:

Field Type Required Notes
id number yes Unique
name string no Readable name
device_group_id number no eg. 1
site_id number no eg. 21
latitude number no eg. null
longitude number no eg. null
time_zone string no eg. "en-GB"
active boolean no true or false

Filters available:

Filter Type
id number
name string
deviceGroupId number
siteId number
latitude number
longitude number
timeZone string
active boolean
sort[field] string as above (except latitude and longitude)
sort[direction] string

Create

curl --location --request POST 'http://localhost/api/v1/devices' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "device" : {
        "name" : "XYZ_ABC",
        "device_group_id" : 1,
        "site_id" : 1,
        "authentication_path" : "/gateway/xyz-abc"
    }
}'

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
    "id": 2,
    "name": "XYZ ABC",
    "device_group_id": 1,
    "site_id": 1,
    "latitude": null,
    "longitude": null,
    "time_zone": "",
    "created_at": "2019-12-13T16:32:11.002Z",
    "updated_at": "2019-12-13T16:32:15.603Z",
    "active": true
}

HTTP Request

POST http://localhost/api/v1/devices

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "device" : { "name" : "XYZ_ABC", "description" : "Test of XYZ Connector" } }

List

curl --location --request GET 'http://localhost/api/v1/devices' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 6,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 42,
            "name": "XyzAbc",
            "device_group_id": 1,
            "site_id": 11,
            "latitude": null,
            "longitude": null,
            "time_zone": "",
            "created_at": "2019-12-13T16:32:11.002Z",
            "updated_at": "2019-12-13T16:32:15.603Z",
            "active": true
        },
        {...}
    ]
}

This command will retrieve a list of devices based on either filter parameters or all devices by default.

HTTP Request

GET http://localhost/api/v1/devices

URL Parameter

Parameter Description
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Update

curl --location --request PUT 'http://localhost/api/v1/devices/3' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain' \
--data-raw '{ "device" : { "authentication_headers" : [] } }'

On Success the command will return:

This command will update a specific device's fields.

HTTP Request

PUT http://localhost/api/v1/devices/<id>

URL Parameter

Parameter Description
id xxx ID to be updated

Content Body

Json string containing: { "device": { "authentication_headers":"???", } }

Headers

Parameter Description
Authorization yourauthtoken

Delete

curl --location --request DELETE 'http://localhost/api/v1/devices/16' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain'

Delete a single device from the system.

HTTP Request

DELETE http://localhost/api/v1/devices/<id>

URL Parameter

Parameter Description
id device ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

History

curl --location --request GET 'http://localhost/api/v1/devices/59/history' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 2,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 38,
            "auditable_id": 42,
            "auditable_type": "Device",
            "associated_id": null,
            "associated_type": null,
            "user_id": 23,
            "user_type": "User",
            "username": null,
            "action": "create",
            "audited_changes": {
                "name": "XyzAbc",
                "active": false,
                "site_id": 21,
                "latitude": null,
                "longitude": null,
                "time_zone": "",
                "account_id": 1,
                "device_group_id": 1,
                "authentication_path": "/gateway/xyzabc",
                "authentication_query": [],
                "authentication_headers": []
            },
            "version": 1,
            "comment": null,
            "remote_address": "127.0.0.1",
            "request_uuid": "005da287-ef80-62c0-9ac2-e7066c7b2250",
            "created_at": "2019-12-13T16:32:11.049Z"
        },
        {
            ...
        }
    ],
    "core_version": "1.1.4"
}

This command will provide details of the audit history for the device.

HTTP Request

GET http://localhost/api/v1/devices/<id>/history

URL Parameter

Parameter Description
id device ID to get history for

Headers

Parameter Description
Authorization yourauthtoken

Assign Tempr to Device

curl --location --request POST 'http://localhost/api/v1/devices/10/assign_tempr?tempr_id=5' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "device_tempr": {
    "endpoint_type": "http",
    "queue_response": true,
    "options": {
      "host": "202.31.132.92",
      "port": 80,
      "path": "/qwe/api/trackedEntityInstances",
      "requestMethod": "POST",
      "protocol": "http",
      "headers":
        {
          "Content-Type": "application/json",
          "Authorization" : "Basic arFjaz0nIVzhNTV6b3Kk"
        }

    }
  }
}'

Assign a Tempr to a single device on the system.

HTTP Request

POST http://localhost/api/v1/devices/<id>/assign_tempr?tempr_id=<tid>

URL Parameter

Parameter Description
id device ID to be assigned to
tid tempr id to assign

Headers

Parameter Description
Authorization yourauthtoken

Device Transmissions

Device Treansmissions have these fields: id device_id tempr_id schedule_id status message_uuid transmission_uuid success transmitted_at created_at updated_at

Filters available:

Filter Type
id number
status number
temprId number
scheduleId number
messageUuid string
transmissionUuid string
success boolean
transmitted_at date time
created_at date time
updated_at date time
sort[field] string as above
sort[direction] string

List

curl --location --request GET 'http://localhost/api/v1/devices/9/transmissions?filter[messageUuid]=9dc5ab1c-8d05-4e5b-8c21-48a7b2f6f241&filter[sort][field]=created_at&filter[sort][direction]=desc' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 25,
            "device_id": 9,
            "tempr_id": null,
            "schedule_id": null,
            "message_uuid": "35f1e645-be21-4eba-af61-cbbb0f9647f8",
            "transmission_uuid": null,
            "success": true,
            "status": 200,
            "transmitted_at": "2019-09-09T13:35:09.693Z",
            "response_body": "{\"messages\":[{\"test\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{\"raw\":{\"name\":\"patient1\",\"result\":\"negative\"}}},\"sample\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{}},\"patient\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{}},\"encounter\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{}}}]}",
            "request_body": null,
            "created_at": "2019-09-09T13:35:10.711Z",
            "updated_at": "2019-09-09T13:35:10.711Z"
        }
    ],
    "core_version": "1.1.4"
}

This command will retrieve a list of transmissions for a device.

HTTP Request

GET http://localhost/api/v1/devices/<id>/transmissions?filter[messageUuid]=<uuid>&filter[sort][field]=created_at&filter[sort][direction]=desc

URL Parameter

Parameter Description
id device id
filter[messageUuid] unique message id
filter[...] see above
filter[sort][field] string field name as above
filter[sort][direction] string either 'asc' or 'desc'

Headers

Parameter Description
Authorization yourauthtoken

Show

curl --location --request GET 'http://localhost/api/v1/devices/9/transmissions' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 42,
            "device_id": 9,
            "tempr_id": null,
            "schedule_id": null,
            "message_uuid": "35f1e645-be21-4eba-af61-cbbb0f9647f8",
            "transmission_uuid": null,
            "success": true,
            "status": 200,
            "transmitted_at": "2019-09-09T13:35:09.693Z",
            "response_body": "{\"messages\":[{\"test\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{\"raw\":{\"name\":\"patient1\",\"result\":\"negative\"}}},\"sample\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{}},\"patient\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{}},\"encounter\":{\"core\":{},\"pii\":{\"custom\":{}},\"custom\":{}}}]}",
            "request_body": null,
            "created_at": "2019-09-09T13:35:10.711Z",
            "updated_at": "2019-09-09T13:35:10.711Z"
        }
    ],
    "core_version": "1.1.4"
}

This command will ...

HTTP Request

GET http://localhost/api/v1/devices/<id>/transmissions/<id>

Headers

Parameter Description
Authorization yourauthtoken

Temprs

A Tempr is a template, mapping, recipe, or schema. It can have one or more of the following fields.

Field Type Required Example
device_group_id number yes
tempr_id number yes
name string yes
description string no
endpoint_type string yes
queue_request boolean ??
queue_response boolean ??
host string yes "your-endpoint.example.com"
port number no 443
path string yes "/api/devices/XYZ/messages?authentication_token=ABCDEX"
request_method string yes "POST"
protocol string yes "https"
language string no "js"
script string no

Filters available:

Filter Type
id number
device_group_id number
name string
description string
sort[field] string as above
sort[direction] string

Create

curl --location --request POST 'http://localhost/api/v1/temprs' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "tempr" : {
      "device_group_id": 2,
      "tempr_id" : 2,
      "name": "XYZ Bridge",
      "description": "The basic request sent from the original XYZ Bridge",
      "endpoint_type": null,
      "queue_request": false,
      "queue_response": false,
      "template": {
        "host": "endpoint.openinterop.local",
        "port": 443,
        "path": "/some/path/to/an/api",
        "request_method": "POST",
        "protocol": "https",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "language": "js",
          "script": "module.exports = { \"event\" : message.message.body }"
        }
      }
}
}'

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 88
}

HTTP Request

POST http://localhost/api/v1/temprs

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "tempr" : { "name" : "XYZ_ABC", "description" : "Test of XYZ Connector" } }

Preview (js)

curl --location --request POST 'http://localhost/api/v1/temprs/preview' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "tempr" : {
    "example_transmission" : "{  \"event\": {    \"COUNTRY_A\": \"UK\",    \"LABORATORY\": \"UTH\",    \"ORIGIN\": \"\",    \"PATIENT_ID\": \"PATTEST4\",    \"LAST_NAME\": \"\",    \"FIRST_NAME\": \"\" }}",
      "template" : {
      "host": "endpoint.openinterop.local",
      "port": 443,
      "path": "/some/path/to/an/api",
      "request_method": "POST",
      "protocol": "https",

      "headers": 
        {
          "Content-Type": "application/json"
        },
    "body" : {
      "language" : "js",
      "script" : "let payload = {   \"trackedEntityType\": \"tuhi0maUrlh\",   \"orgUnit\": message.message.body.event.FARM_NUM,   \"attributes\": [     {       \"attribute\": \"udQ5rLwup6d\",       \"value\": message.message.body.event.SPEC_NUM     },     {       \"attribute\": \"wAr0ZjIO0d8\",       \"value\": \"WNet_Animal\"     }   ],   \"enrollments\": [     {       \"orgUnit\": message.message.body.event.FARM_NUM,       \"program\": \"sWf6NXIupFI\",       \"programStage\": \"kGfHGNWI6iQ\",       \"enrollmentDate\": message.message.body.event.SPEC_DATE,       \"incidentDate\": message.message.body.event.SPEC_DATE,       \"events\": [         {           \"program\": \"sWf6NXIupFI\",           \"orgUnit\": message.message.body.event.FARM_NUM,           \"eventDate\": message.message.body.event.SPEC_DATE,           \"status\": \"COMPLETED\",           \"programStage\": \"kGfHGNWI6iQ\",           \"dataValues\": [               { \"dataElement\" : \"h74xyBYnXPB\", \"value\" : message.message.body.event.AMP_ND10 },               { \"dataElement\" : \"hMbQTNDTia2\", \"value\" : message.message.body.event.CPD_ND10 },               { \"dataElement\" : \"IYXfvQ9nS4O\", \"value\" : message.message.body.event.CIP_ND5 },               { \"dataElement\" : \"gnX3CxdocmO\", \"value\" : message.message.body.event.TCY_ND30 },               { \"dataElement\" : \"OxT8HFtgtCW\", \"value\" : message.message.body.event.GEN_ND10 },               { \"dataElement\" : \"zyXV5PZjiBm\", \"value\" : message.message.body.event.SXT_ND1_2 },               { \"dataElement\" : \"Wsk4NARIElI\", \"value\" : message.message.body.event.ORGANISM },               { \"dataElement\" : \"IvVVi4ft0v8\", \"value\" : message.message.body.event.SPEC_TYPE  }           ]         }       ]     }   ] };  module.exports = payload; "
    } }
  }
}'

On Success the command returns JSON structured like this:

{
    "rendered": {
        "host": "endpoint.openinterop.local",
        "port": "443",
        "path": "/some/path/to/an/api",
        "request_method": "POST",
        "protocol": "https",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": "{\"trackedEntityType\":\"tuhi0maUrlh\",\"attributes\":[{\"attribute\":\"udQ5rLwup6d\"},{\"attribute\":\"wAr0ZjIO0d8\",\"value\":\"WNet_Animal\"}],\"enrollments\":[{\"program\":\"sWf6NXIupFI\",\"programStage\":\"kGfHGNWI6iQ\",\"events\":[{\"program\":\"sWf6NXIupFI\",\"status\":\"COMPLETED\",\"programStage\":\"kGfHGNWI6iQ\",\"dataValues\":[{\"dataElement\":\"h74xyBYnXPB\"},{\"dataElement\":\"hMbQTNDTia2\"},{\"dataElement\":\"IYXfvQ9nS4O\"},{\"dataElement\":\"gnX3CxdocmO\"},{\"dataElement\":\"OxT8HFtgtCW\"},{\"dataElement\":\"zyXV5PZjiBm\"},{\"dataElement\":\"Wsk4NARIElI\"},{\"dataElement\":\"IvVVi4ft0v8\"}]}]}]}"
    },
    "console": ""
}

HTTP Request

POST http://localhost/api/v1/temprs/preview

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "tempr" : { "example_transmission" : "transmission data layout", "template" : { "host": "endpoint.openinterop.local", "port": 443, "path": "/some/path/to/an/api", "request_method": "POST", "protocol": "https", "headers": { "Content-Type": "application/json" }, "body" : { "language" : "moustache", "body" : "content of the template display" } } } }

Preview (moustache)

curl --location --request POST 'http://localhost/api/v1/temprs/preview' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "tempr" : {
    "example_transmission" : "{  \"event\": {    \"COUNTRY_A\": \"UK\",    \"LABORATORY\": \"UTH\",    \"ORIGIN\": \"\",    \"PATIENT_ID\": \"PATTEST4\",    \"LAST_NAME\": \"\",    \"FIRST_NAME\": \"\" }}",
      "template" : {
      "host": "endpoint.openinterop.local",
      "port": 443,
      "path": "/some/path/to/an/api",
      "request_method": "POST",
      "protocol": "https",

      "headers": 
        {
          "Content-Type": "application/json"
        },
    "body" : {
      "language" : "moustache",
      "body" : "asd of this thing {{message.body.event.COUNTRY_A}} and also {{message.body.event.PATIENT_ID}}"
    } }
  }
}'

On Success the command returns JSON structured like this:

{
    "rendered": {
        "host": "endpoint.openinterop.local",
        "port": "443",
        "path": "/some/path/to/an/api",
        "request_method": "POST",
        "protocol": "https",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": {
            "language": "moustache",
            "body": "asd of this thing UK and also PATTEST4"
        }
    },
    "console": ""
}

HTTP Request

POST http://localhost/api/v1/temprs/preview

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { "tempr" : { "example_transmission" : "transmission data layout", "template" : { "host": "endpoint.openinterop.local", "port": 443, "path": "/some/path/to/an/api", "request_method": "POST", "protocol": "https", "headers": { "Content-Type": "application/json" }, "body" : { "language" : "moustache", "body" : "content of the template display" } } } }

List

curl --location --request GET 'http://localhost/api/v1/temprs' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

On Success the command will return:

{
    "total_records": 5,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 56,
            "device_group_id": 1,
            "tempr_id": null,
            "name": "Dummy passthrough",
            "description": "",
            "endpoint_type": "http",
            "queue_request": true,
            "queue_response": true,
            "template": {
                "headers": {},
                "host": "localhost",
                "path": "/gateway/dummy-no-auth",
                "port": 9009,
                "protocol": "http",
                "request_method": "POST",
                "body": {
                    "language": "js",
                    "script": "module.exports = message.message.body"
                }
            },
            "example_transmission": null,
            "notes": "",
            "created_at": "2019-12-11T09:08:09.458Z",
            "updated_at": "2019-12-11T09:08:09.458Z"
        },
        {...}
    ],
    "core_version": "1.1.4"
}

This command will retrieve a list of Temprs on the system, matching supplied filters or all

HTTP Request

GET http://localhost/api/v1/temprs

URL Parameter

Parameter Description
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Update

curl --location --request PUT 'http://localhost/api/v1/temprs/68' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "tempr" : {
    "tempr_id" : 64
  }
}'

On Success the command will return:

This command will ...

HTTP Request

PUT http://localhost/api/v1/temprs/<id>

URL Parameter

Parameter Description
id tempr ID to be updated

Content Body

Json string containing: { "tempr": { "tempr_id":"1234", } }

Headers

Parameter Description
Authorization yourauthtoken

Delete

curl --location --request DELETE 'http://localhost/api/v1/temprs/65' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain' \
--data-raw '{}'

Delete a single tempr from the system.

HTTP Request

DELETE http://localhost/api/v1/temprs/<id>

URL Parameter

Parameter Description
id tempr ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

History

curl --location --request GET 'http://localhost/api/v1/temprs/56/history' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 289,
            "auditable_id": 56,
            "auditable_type": "Tempr",
            "associated_id": null,
            "associated_type": null,
            "user_id": 1,
            "user_type": "User",
            "username": null,
            "action": "create",
            "audited_changes": {
                "body": {},
                "name": "Dummy passthrough",
                "notes": "",
                "template": {
                    "body": {
                        "script": "module.exports = message.message.body",
                        "language": "js"
                    },
                    "host": "openinterop.local",
                    "path": "/gateway/dummy-no-auth",
                    "port": 9009,
                    "headers": {},
                    "protocol": "http",
                    "request_method": "POST"
                },
                "tempr_id": null,
                "account_id": 1,
                "description": "",
                "endpoint_type": "http",
                "queue_request": true,
                "queue_response": true,
                "device_group_id": 1,
                "example_transmission": null
            },
            "version": 1,
            "comment": null,
            "remote_address": "127.0.0.1",
            "request_uuid": "93740d5d-5935-44a8-b8ba-a2eae9e07d79",
            "created_at": "2019-12-11T09:08:09.469Z"
        }
    ],
    "core_version": "1.1.4"
}

This command will ...

HTTP Request

GET http://localhost/api/v1/temprs/<id>/history

URL Parameter

Parameter Description
id tempr ID to get history for

Headers

Parameter Description
Authorization yourauthtoken

Schedule Temprs

The Schedule Temprs can have one or more of the following fields:

Field Type Required Notes
id number yes Unique
schedule_id number yes
tempr_id number yes

Create

curl --location --request POST 'http://localhost/api/v1/schedule_temprs?tempr_id=1&schedule_id=1' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--data-raw ''

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 88,
  "schedule_id": 1,
  "tempr_id": 59
}

HTTP Request

POST http://localhost/api/v1/schedule_temprs?tempr_id=<tid>&schedule_id=<sid>

Headers

Parameter Description
Authorization yourauthtoken

URL Parameter

Parameter Description
tid tempr ID
sid schedule ID

Content Body

Json string containing: { }

List

curl --location --request GET 'http://localhost/api/v1/schedule_temprs?filter[schedule_id]=1' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 1,
            "schedule_id": 1,
            "tempr_id": 59
        }
    ],
    "core_version": "1.1.4"
}

This command will ...

HTTP Request

GET http://localhost/api/v1/schedule_temprs?filter[schedule_id]=<sid>

URL Parameter

Parameter Description
sid schedule ID
filter[xx] yy

Headers

Parameter Description
Authorization yourauthtoken

Delete

curl --location --request DELETE 'http://localhost/api/v1/schedule_temprs/1?device_id=4&tempr_id=8' \
--header 'Content-Type: application/json' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: text/plain'

Delete a single schedule from the system.

HTTP Request

DELETE http://localhost/api/v1/schedule_temprs/<id>?device_id=<did>&tempr_id=<tid>

URL Parameter

Parameter Description
id schedule temprs ID to be deleted
did device ID
tid tempr ID

Headers

Parameter Description
Authorization yourauthtoken

Device Temprs

The Device Temprs can have one or more of the following fields:

Field Type Required Notes
id number yes Unique
device_id number yes eg. 5
tempr_id number yes eg. 2

Filters available:

Filter Type
id number
device_id number
tempr_id number
sort[field] string as above
sort[direction] string

Create

curl --location --request POST 'http://localhost/api/v1/device_temprs?tempr_id=1&device_id=3' \
--header 'Authorization: yourauthtoken' \
--header 'Content-Type: application/json' \
--data-raw ''

If there is a problem then the command returns JSON structured like this (with multiple errors the fields will each have an entry):

{
  "<fieldname>": [
    "<error message details>"
  ]
}

On Success the command returns JSON structured like this:

{
  "id": 88
}

HTTP Request

POST http://localhost/api/v1/device_temprs

Headers

Parameter Description
Authorization yourauthtoken

Content Body

Json string containing: { }

List

curl --location --request GET 'http://localhost/api/v1/device_temprs?filter[tempr_id]]=2' \
--header 'Authorization: yourauthtoken'

On Success the command will return:

{
    "total_records": 1,
    "number_of_pages": 1,
    "page": {
        "number": 1,
        "size": 20
    },
    "data": [
        {
            "id": 6,
            "device_id": 6,
            "tempr_id": 2
        }
    ],
    "core_version": "1.1.4"
}

This command will return a list of device to temprs links

HTTP Request

GET http://localhost/api/v1/device_temprs

URL Parameter

Parameter Description
filter[tempr_id] unique temprs id

Headers

Parameter Description
Authorization yourauthtoken

Delete

curl --location --request DELETE 'http://localhost/api/v1/device_temprs/10?device_id=9&tempr_id=4' \
--header 'Authorization: yourauthtoken'

Delete a single device temprs from the system.

HTTP Request

DELETE http://localhost/api/v1/device_temprs/<id>?device_id=<did>&tempr_id=<tid>

URL Parameter

Parameter Description
id device_temprs ID to be deleted
did device ID to be deleted
tid temprs ID to be deleted

Headers

Parameter Description
Authorization yourauthtoken

Microservices

The core token is predefined when the core is setup - see Jacks Documentation (LOL!)

List Devices Auth

curl --location --request GET 'http://localhost/services/v1/devices/auth' \
--header 'X-Core-Token: yourcoretoken'

On success returns:

[
    {
        "id": 8,
        "authentication": {
            "hostname": "openinterop.local",
            "headers.x-api-key": "some-api-key"
        },
        "tempr_url": "http://localhost/services/v1/devices/8/temprs"
    },
    {
        ...
    }
]

HTTP Request

GET http://localhost/services/v1/devices/auth

Headers

Parameter Description
X-Core-Token yourcoretoken

List Temprs for Device

curl --location --request GET 'http://localhost/services/v1/devices/5/temprs' \
--header 'X-Core-Token: yourcoretoken' \
--header 'Content-Type: application/json'

On success returns:

{
    "ttl": 300000,
    "data": [
        {
            "id": 1,
            "deviceId": 5,
            "scheduleId": null,
            "name": "ABC XYZ",
            "endpointType": null,
            "queueRequest": false,
            "queueResponse": false,
            "template": {},
            "createdAt": "2019-08-30T08:59:17.321Z",
            "updatedAt": "2019-09-09T12:49:56.297Z",
            "temprs": []
        },
        {...}
    ]
}

HTTP Request

GET http://localhost/services/v1/devices/<id>/temprs

Headers

Parameter Description
X-Core-Token yourcoretoken

URL Parameter

Parameter Description
id device ID

List Temprs for Schedule

curl --location --request GET 'http://localhost/services/v1/schedules/1/temprs' \
--header 'X-Core-Token: yourcoretoken'

On success returns:

HTTP Request

GET http://localhost/services/v1/schedules/<id>/temprs

Headers

Parameter Description
X-Core-Token yourcoretoken

URL Parameter

Parameter Description
id schedule ID

List Schedules

curl --location --request GET 'http://localhost/services/v1/schedules' \
--header 'X-Core-Token: yourcoretoken'

On success returns:

HTTP Request

GET http://localhost/services/v1/schedules

Headers

Parameter Description
X-Core-Token yourcoretoken