GuidesAPI ReferenceForum
Guides
Login

Using the REST API in an External System

Suggest Edits

Octave provides a REST API consisting of Octave objects (e.g., Devices, Events, etc.) that you can invoke from an external cloud system to read or push data into Octave. For example, you can use the REST API to update devices in your deployment. create Events, etc. from any external system that has internet access.

Sending Events to Octave

This section provides a simple example of using the REST API's Event Object to create Events for a specific device. In this example, the POST /{company ID}/event/{stream ID} endpoint is used to post an Event with a single key/value (measure) to a Stream. For additional information see: Setting a Value From a REST API Call.

📘

Note

In order to invoke the endpoints, you must first obtain your master token and user ID. These are both available on the user screen in the Octave Dashboard.

Request

The example below sends a new event to Stream s5b7310ae6f38613585853e5b:

curl -X "POST" "https://octave-api.sierrawireless.io/v5.0/my_company/event/s5b7310ae6f38613585853e5b" \
     -H 'X-Auth-Token: <token>' \
     -H 'X-Auth-User: <user>' \
     -d $'{
  "elems": {
    "measure": 7
  }
}'

📘

Note

You can identify Stream IDs by opening the Octave dashboard and navigating to Device > Streams or Cloud > Streams, clicking on a Stream, and the locating the Stream ID in your browser's URL.

Response

The messages field in the response indicates the result of the request and the id indicates the ID of the Event that was added:

{
   "head":{
      "status":201,
      "ok":true,
      "messages":[
         "Your request has been processed successfully. A new resource has been created."
      ],
      "errors":[

      ],
      "references":{

      }
   },
   "body":{
      "id":"e5b7311856f38613585853e61",
      "streamId":"s5b7310ae6f38613585853e5b",
      "creationDate":1534267781805,
      "generatedDate":1534267781805,
      "path":"/my_company/streamname",
      "version":0,
      "elems":{
         "measure":7
      }
   }
}

Getting Events from Octave

You can use the Octave REST API to GET events from Octave.

Example Request 1 - Getting Events by Specifying a Stream ID

The following shows how to issue a GET request, specifying the ID of an Event Stream from which to return Events:

curl -X "GET" "https://octave-api.sierrawireless.io/v5.0/my_company/event/s5f6d0..." \
     -H 'X-Auth-Token: <token>' \
     -H 'X-Auth-User: <user>' 
}'

Example Request 2 - Getting Events by Specifying a Stream Path

The following shows how to issue a GET request, specifying the path of an Event Stream in the path query parameter from which to return events:

curl -X "GET" "https://octave-api.sierrawireless.io/v5.0/my_company/event?path=/my_company/some_task_output" \
     -H 'X-Auth-Token: <token>' \
     -H 'X-Auth-User: <user>' 
}'

Response
The body field in the response contains the information for each Event:

{
   "head":{
      "status":200,
      "ok":true,
      "messages":[
         
      ],
      "errors":[
         
      ],
      "references":{
         
      }
   },
   "body":[
      {
         "id":"e5f73779a83a82cbbd98a6fb9",
         "streamId":"s5f6d05970940dec3af5728fd",
         "creatorId":"i5c75885f6a31c10d1f728c7c",
         "lastEditorId":"i5c75885f6a31c10d1f728c7c",
         "metadata":null,
         "creationDate":1601402778785,
         "lastEditDate":1601402778785,
         "generatedDate":null,
         "path":"/my_company/some_task_output",
         "location":null,
         "hash":null,
         "tags":{
            
         },
         "elems":{
            "measure":7
         }
      },
      {
         "id":"e5f7377298a1a387a846170a3",
         "streamId":"s5f6d05970940dec3af5728fd",
         "creatorId":"i5c75885f6a31c10d1f728c7c",
         "lastEditorId":"i5c75885f6a31c10d1f728c7c",
         "metadata":null,
         "creationDate":1601402665446,
         "lastEditDate":1601402665446,
         "generatedDate":null,
         "path":"/my_company/some_task_output",
         "location":null,
         "hash":null,
         "tags":{
            
         },
         "elems":{
            "else":true,
            "time":2
         }
      }
   ]
}

Updated about 3 years ago