Technical Reference

Using the REST API in an External System

Octave provides a REST API for reading and interacting with Octave Domain Objects (e.g., Devices, Events, etc.)

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.

📘

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.

Alternatively you can invoke POST /stream to create a new Stream, which will return the ID in the response, or invoke GET /stream to return a list of all Streams including their IDs

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

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 retrieve Events from Octave.

Example Request 1 - Getting Events by Specifying a Stream ID

📘

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.

Alternatively you can invoke POST /stream to create a new Stream, which will return the ID in the response, or invoke GET /stream to return a list of all Streams including their IDs

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
         }
      }
   ]
}