LX IoT Core Event Pull APIs

Paging ¶

Events are returned in batches of events. The default is 100 events per batch.

The events are designed to be treated as a stream. By saving the position you were up to in the stream you can pull only events you haven’t received before.

Your first read should use 0 as the position value, which will start you at the beginning.

NOTE: While the position is an integer number it doesn’t relate to the number of events being returned or the size of the events on disk. Your code should not try to make sense of what it is, just use it to remember where you were up to.

Each request includes a link in the response to fetch the next batch of events. This link will include the position information, so you can also just save the link and use it next time you would like to pull newer data.

Here is an example of the response you’ll receive when you reach the end of the stream.

{
      "organisation": "example_org",
      "project": "example_project",
      "events": [],
      "_links": { //_
        "self": {
          "href": "/v0/orgs/example_org/projects/example_project/events?position=82574&pageSize=0"
        },
        "next-page": {
          "href": "/v0/orgs/example_org/projects/example_project/events?position=82574",
          "title": "Get the next page of events"
        }
      }
    }

• organisation is the organisation these events belong to.

• project is the project within the organisation the events are grouped under.

• events is an array which contains the events as JSON objects. If you receive less than the number of events you requested (the default is 100) it means you are at the end of the stream.

• _links contains links to other API functions.

  • self contains a URL that can load this exact same set of events again. In this example it wouldn’t load any events as none were returned. This is mostly useful if you need give someone a link to where you received some data of interest as it allows them to quickly find what you saw.
  • next-page contains the URL that should be used to get the next page of events. Use the href field.

Special Position Values ¶

📖  Quite often while doing testing or diagnostics it is helpful to quickly retrieve a handful of recent events. Rather than starting at position 0 or guessing a random position and working towards the end of the stream, which can be quite time consuming a convenient method of retrieving the last n events is provided.

To retrieve the last n events simply use -n as the position. For example to fetch the last 5 events make the request with position=-5.

Please note when using this approach that events will still be returned in batches as determined by the page size.