File Sending Reference

File Service Events

You can retrieve the following Events handled through the file service Resources as part of file-sending process:

Interface

Direction

Description

Path

Data

File-sending pending

Device → Remote Asset

A new file can be sent

/files/download/value

{
    "name": <file name>,
    "autostart": false/true,
    "state": "waiting",
    "remaining": <size in bytes>,
    "progress": 0
}

File-sending progress

Device → Remote Asset

Notification with number of sent bytes

/files/download/value

{
    "name": "newfile.dat",
    "autostart": false/true,
    "state": "transferring",
    "remaining": <size in bytes>,
    "progress": x
}

Note: During file download, this notification is sent when the progress value changes.

File-sending suspended

Device → Remote Asset

Notification when a File-sending operation is suspended

/files/download/value

{
    "name": "newfile.dat",
    "autostart": false/true,
    "state": "waiting",
    "remaining": <size in bytes>,
    "progress": x
}

File-sending end

Octave Edge Device → Remote Asset

Notification when a File-sending operation ends

/files/download/value

{
    "name": "newfile.dat",
    "autostart": false/true,
    "state": "success",
    "size": <size in bytes>,
    "progress": 100
}

File-sending failure

Octave Edge Device → Remote Asset

Notification when a File-sending operation fails

/files/download/value

{
    "name": "newfile.dat",
    "autostart": false/true,
    "state": "failure",
    "remaining": <size in bytes>,
    "progress": x
}

File-sending abortion

Octave Edge Device → Remote Asset

Notification when a File-sending operation was aborted (by an asset or the server)

/files/download/value

{
    "name": "newfile.dat",
    "autostart": false/true,
    "state": "aborted",
    "remaining": 0,
    "progress": 0
}

File availability

Octave Edge Device → Remote Asset

Notification when a file can be retrieved by the asset.

This notification is pushed by the Octave file service when a file is fully and successfully sent and when it's deleted.

/files/list/value

{
    "path": <path>,
    "files":[
        {
            "name": "file name 1",
            "hash": "hash 1",
            "size": 12345,
            "origin": 0
        },
        {
            "name": "file name 2",
            "hash": "hash 2",
            "size": 987654,
            "origin": 0
        }
    ]
}

origin: 0 for server origin (file download)

Accept or resume a transfer

Remote Asset → Octave Edge Device

The host accepts the pending transfer.

An error could be returned if no file is available for sending.

Before 3.2.0:
/files/control/value

From 3.2.0:
/files/control

{
   "name": "file name",
   "transfer": "start"
}

Suspend a transfer

Remote Asset → Octave Edge Device

The host requests to suspend the download.

An error could be returned if no download is on-going.

The host can resume the download.

Before 3.2.0:
/files/control/value

From 3.2.0:
/files/control

{
   "name": "file name",
   "transfer": "pause"
}

Abort a transfer

Remote Asset→ Octave Edge Device

The host requests to abort the download.

An error could be returned if no download is on-going.
The partial file is deleted.

Before 3.2.0:
/files/control/value

From 3.2.0:
/files/control

{
   "name": "file name",
   "transfer": "abort"
}

Delete a file

Remote Asset→ Octave Edge Device

The host requests to delete a file which is available (meaning, fully deleted. To delete a file which is currently downloading, first issue an "abort" before attempting to delete. You can check this via File-sending progress.)

An error could be returned if the file is not present.

Before 3.2.0:
/files/control/value

From 3.2.0:
/files/control

{
   "name": "file name",
   "transfer": "delete"
}

Examples of API Requests

File API

Create File

Request

curl -X "POST" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/file" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username' \
     -F "[email protected]" \
     -F "params={\"description\" : \"a description\"}"

Response

{
  "head": {
    "status": 201,
    "ok": true,
    "messages": [
      "Your request has been processed successfully. A new resource has been created."
    ],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "avFileId": "<id>",
    "companyId": "<id>",
    "creationDate": <date>,
    "creatorId": "<id>",
    "description": "a description",
    "filename": "yoshi.png",
    "filetype": "image/png",
    "hash": "<hash>",
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "path": "/farm",
    "size": 642729,
    "source": "CLOUD",
    "version": 1
  }
}

Update a File

Request

curl -X "PUT" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username' \
     -F "[email protected]" \ 
     -F "params={}"

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "avFileId": "<id>",
    "companyId": "<id>",
    "creationDate": <date>,
    "creatorId": "<id>",
    "description": "a description",
    "filename": "yoshi.png",
    "filetype": "image/png",
    "hash": "<hash>",
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "path": "/farm",
    "size": 772642,
    "source": "CLOUD",
    "version": 2
  }
}

Get File

Request

curl -X "GET" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username’ \
     -F "params={}"

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "avFileId": "<id>",
    "companyId": "<id>",
    "creationDate": <date>,
    "creatorId": "<id>",
    "description": "a description",
    "filename": "yoshi.png",
    "filetype": "image/png",
    "hash": "<hash>",
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "path": "/farm",
    "size": 772642,
    "source": "CLOUD",
    "version": 2
  }
}

Delete a File

Request

curl -X "DELETE" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username'

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [
      "Your request has been processed successfully. The requested resource has been deleted."
    ],
    "errors": [],
    "references": {}
  },
  "body": {}
}

Send API

Get File

*Request

curl -X "POST" "" https://octave-api.sierrawireless.io/v5.0/farm/device/file/send"
 \
     -H 'X-Auth-Token: {token}\
     -H 'X-Auth-User: usnername' \
     -d $'{
  "fileIds" : {"fileId" : {"version" : 1}},
  "deviceIds" : ["{deviceId}","{deviceId}"]
}'

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": {
    "id": "<id>",
    "action": "SEND_FILE",
    "companyId": "<id>",
    "complete": false,
    "creationDate": <date>,
    "creatorId": "<id>",
    "details": {},
    "deviceIds": [],
    "input": {
      "deviceIds": [
        "{deviceId}",
        "{deviceId}"
      ]
    },
    "lastEditDate": <date>,
    "lastEditorId": "<id>",
    "state": "STARTED",
    "status": {},
    "stepCount": 2,
    "timeout": 86400
  }
}

Operation API

Get File

Request

curl -X "GET" " https://octave-api.sierrawireless.io/ /v5.0/{company_name}/operation/{id]" \
     -H 'X-Auth-Token: XXXX' \
     -H 'X-Auth-User: username’ \

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": []
  },
  "body": {
    "companyId": "string",
    "creationDate": 1553558878392,
    "lastEditDate": 1553558878392,
    "id": "o5c37879220721249d5c8ffa3",
    "action": "TRANSFER_DEVICE",
    "complete": true,
    "state": "UNKOWN",
    "status": {
      "d5b73101dc4eaa254868f2e7b": {
        "PUSH_CONFIGURATION": {
          "state": "STARTED",
          "ts": 1553560620870
        }
      }
    }
  }
}