API Example Usage

The API powering Flow is based on Websockets where RPC Endpoints are published by Flow's various subsystems.

The API supports 7 methods, these are:

Method	Description	Object ID	Data
LIST	List all objects from endpoint	No	No
OPEN	Open specific object	Yes	No
UPDATE	Update specific object	Yes	Yes
DELETE	Delete existing object	Yes	No
INDEX	Retrieve search information about objects	Yes	No
CREATE	Create object	No	Yes
RUN	Execute method or flow	Yes	Yes

Deepstream Websockets

All calls to Flow's APIs going through the websocket engine follow the structure:

{
  "method": "LIST/OPEN/CREATE/UPDATE/DELETE/INDEX/RUN",
  "objectid": "", // Needed for methods affecting existing objects
  "token": "", // Authentication token
  "namespace": "", // Namespace

  "parameters": "", // Parameters
  "data": {} // Needed for Create, Update & Run
}

Method & Token are always required regardless of the type of call made, objectid is only needed when the call involves a specific object in the database, e.g., Open, Update, Delete.

Data is required for operations where data in some form is to be saved as a result of the call.

Regardless of the type of call made or the type of response received, the structure is always the same, see examples of these responses below:

Fetching a device

Call to /inventory/device =>

{
  "method": "OPEN",
  "objectid": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
  "token": "Token generated by Authentication engine",
}

Response with error

{
  "status": 0,
  "success": false,
  "message": "Object does not exist",
  "errorcode": "DO_NOT_EXIST",
  "dataType": "JSON",
  "errorid": "7981f103-142e-41bf-ae39-ff1341de35f6"
}

Response with data

{
  "status": 0,
  "success": true,
  "data": {
    "id": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
    "created": "2017-07-10T09:23:50Z",
    "updated": "2018-03-27T09:27:40Z",
    "name": "5128v1.3 (Core-MGNT-switch)",
    "..."
  },
  "dataType": "JSON"
}

The attribute "success": true/false is always present regardless of whether the call was successful or not.

HTTP

Flow's internal RPC endpoints are automatically published as an HTTP REST JSON API, which can be utilized to integrate third-party software with Flow. Responses from calls made over HTTP have the same structure as responses from Websockets since they are passed through without modification, the difference between calls over Websockets and HTTP is that all call data outside the data parameter is sent as HTTP Headers instead of in the object.

To make a call, you compose your URL in this way:

https://(address to flow gui)/api/(application name)/(rpc endpoint)/(object id)

e.g., https://flow.local/api/scheduler/scheduler/queue/ HTTP GET can be used for LIST, OPEN, and DELETE operations while HTTP POST can be used for CREATE and UPDATE operations.

Note that the / after queue is mandatory as it is part of the endpoint, ending without / assumes the last segment to be an object ID.

Everything in FlowRequest except for the data itself is either placed in headers or in the query string.

HTTP Header	Query string
Flow-Auth-Token	token
Flow-Request-ObjectId	objectid
Flow-Request-Namespace	namespace
Flow-Request-Method	method

Authentication via HTTP API The API handles two ways to authenticate, either HTTP Basic Auth or with a token. Both methods use headers.

HTTP Basic AUTH : Authorization: Basic base64(username:password)

Sending token through header: Flow-Auth-Token: Token från Autentiserinsmotorn

Example

Fetch a device

Websockets

Call to /inventory/device =>

{
  "method": "OPEN",
  "objectid": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
  "token": "Token generated by Authentication engine",
}

Response =>

{
  "status": 0,
  "success": true,
  "data": {
    "id": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
    "created": "2017-07-10T09:23:50Z",
    "updated": "2018-03-27T09:27:40Z",
    "name": "5128v1.3 (Core-MGNT-switch)",
    "..."
  },
  "dataType": "JSON"
}

HTTP

GET flow.local/api/inventory/inventory/device
headers
  Flow-Auth-Token: "Token generated by Authentication engine"
  Flow-Request-ObjectId: "3a472a78-4e3e-4858-8acc-eb754f9d1328"
  Flow-Request-Method: "OPEN"

Response =>

{
  "status": 0,
  "success": true,
  "data": {
    "id": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
    "created": "2017-07-10T09:23:50Z",
    "updated": "2018-03-27T09:27:40Z",
    "name": "5128v1.3 (Core-MGNT-switch)",
    "..."
  },
  "dataType": "JSON"
}

Update a device

Websockets

Call to /inventory/device =>

{
  "method": "UPDATE",
  "objectid": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
  "token": "Token generated by Authentication engine",
  "data": {
    "name": "New name for switch"
  }
}

Response =>

{
  "status": 0,
  "success": true,
  "data": {
    "id": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
    "created": "2017-07-10T09:23:50Z",
    "updated": "2018-03-27T09:27:40Z",
    "name": "New name for switch",
    "..."
  },
  "dataType": "JSON"
}

HTTP

POST flow.maintrac.net/api/inventory/inventory/device
headers
  Flow-Auth-Token: "Token generated by Authentication engine"
  Flow-Request-ObjectId: "3a472a78-4e3e-4858-8acc-eb754f9d1328"
  Flow-Request-Method: "UPDATE"
body
  {
    "name": "New name for switch"
  }

Response =>

{
  "status": 0,
  "success": true,
  "data": {
    "id": "3a472a78-4e3e-4858-8acc-eb754f9d1328",
    "created": "2017-07-10T09:23:50Z",
    "updated": "2018-03-27T09:27:40Z",
    "name": "New name for switch",
    "..."
  },
  "dataType": "JSON"
}