Lightstream-doc.md

Lightstream API

Lightstream is a solution which allows you to map any kind of geocalized data in real time. Lightstream API is the backend entry you want to use to push your items, so you can visualize them on the front end. This documentation will help you understand how easy it is to use .

Index

• Items and types explains why items and types are important in Lightstream
• API access gives you all information to access the API.
• API lists all API endpoints available

Items and types

An item is the simplest representation of data managed by Lightstream. An item has coordinates, is pushed to Lightstream through the API, and displayed on the map, either in history mode or in real time.

Lightstream distinctively displays received items, based on their type. The item type is essential in Lightstream, to improve visualization and get a better user experience. You may or may not want to display, for example, a temperature or the strength and direction of a wind the same way. You can push several types of items to the API, as long as they have been defined and configured in the API. When deploying the API, you can define types either precisely, or by using a generic definition of your data, depending on your needs.

Item representation

Item are usually represented in the following JSON :

{
  "geojson": {
    "type": "Point",
    "coordinates": [43.6, 3.9]
  },
  "id": 3,
  "data": {
    "message": "hey!"
  }
}

Item coordinates are based on GeoJSON specification. The geojson property is a GeoJSON Geometry Object. When an item is pushed, it must fit to the declared geometry object in the API configuration (Point in the example). In the previous example, the coordinates of the point are declared the geojson way, meaning [longitude, latitude].

An item has an optional id property. When not given, an id is automatically defined.

The property data represents any kind of data needed to filter or display. The property is mandatory, but its content is totally free.

Type representation

As you might have noticed, the item type is not represented in its structure. The type is provided directly in the API URLs, when dealing with items.

API access

The API is accessible through the URL: http://<any_subdomain>.lightsream.io/api

The host can differ, depending on the type of installation: either in SaaS mode or on premise. For the following examples, the host example.lightstream.iowill be used.

Content type

Lightstream API only supports JSON to communicate data, in both ways.

Security

In order to secure the API access, an API key is needed. The API key must be provided as a query parameter, like in the following example: http://<any_subdomain>.lightsream.io/api/<any_path>?api_key=<your_api_key>

In the following examples, the api key will be ignored, for better clarity.

API

Index

• Status gives you the status of the API
• Items to push an item, and retrieve it by its id
  • Push an item into Lightstream
  • Get an item already pushed to Lightstream

Status

GET http://example.lightstream.io/api/status

This endpoint allows you to know about the status of the API. Always return:

{
  "status": "ok"
}

Of course, if the API is down, this call is impossible.

Items

Push an item

POST http://example.lightstream.io/api/items/:type

{
  "geojson": {
    "type": "Point",
    "coordinates": [43.6, 3.9]
  },
  "id": 3,
  "data": {
    "message": "hey!"
  }
}

This endpoint allows you to push an item into Lightstream. This same endpoint allows you to update an item, if the item with the same id has already been pushed. It takes the following parameters:

• The type parameter is provided in the path. It represents the item's type.
• The item is provided in the request body, as a JSON.

It can return the following HTTP status code:

• 200: the item has been saved by Lightstream. No body is provided.
• 404: either the url is unknown, or the type in unknown from the API if the URL is right. Check either the URL or the type parameter.
• 500: an internal error has occurred in the API while receiving the item. Try to resend the item later, or call the administrator.

Get an item

GET http://example.lightstream.io/api/items/:type/:id

This endpoint allows you to get an item previously pushed by its id. It takes the following parameters:

• The type parameter is provided in the path. It represents the item's type.
• The id parameter is provided in the path. It represents the item's id.

It can return the following HTTP status code:

• 200: the item has been found by Lightstream. The item is returned in the response body.
• 404: the item has not been found.

Response body:

{
  "geojson": {
    "type": "Point",
    "coordinates": [43.6, 3.9]
  },
  "id": 3,
  "data": {
    "message": "hey!"
  }
}