API Usage

Orion Context Broker exposes a REST API that allows users to interact with the context data, including creating, updating, querying entities, and managing subscriptions.

Here are the most common API operations:

Creating an Entity

To create an entity, use the following API request:

curl -iX POST \
  'http://<orion_host>:1026/v2/entities' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "_Room1_",
    "type": "Room",
    "temperature": {
      "value": 23,
      "type": "Float"
    },
    "humidity": {
      "value": 50,
      "type": "Float"
    }
  }'

id: Unique identifier for the entity.
type: Defines what the entity represents (in this case, a "Room").
Attributes: Key-value pairs such as temperature and humidity are defined.

Updating an Entity’s Attribute

To update an entity’s attribute (e.g., changing the temperature), use the following API call:

curl -iX PATCH \
  'http://<orion_host>:1026/v2/entities/_Room1_/attrs' \
  -H 'Content-Type: application/json' \
  -d '{
    "temperature": {
      "value": 25,
      "type": "Float"
    }
  }'

This updates the temperature attribute of the entity Room1.

Querying an Entity

To retrieve information about a specific entity, send a GET request:

curl -X GET 'http://<orion_host>:1026/v2/entities/_Room1_'

This will return the current attributes and their values for the Room1 entity.

Creating a Subscription

Subscriptions allow applications to receive notifications when certain conditions are met. Below is an example of how to create a subscription to receive notifications when the temperature attribute of an entity changes:

curl -iX POST \
  'http://<orion_host>:1026/v2/subscriptions' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Notify when temperature changes",
    "subject": {
      "entities": [
        {
          "id": "Room1",
          "type": "Room"
        }
      ],
      "condition": {
        "attrs": ["temperature"]
      }
    },
    "notification": {
      "http": {
        "url": "http://<notification_host>:5050/notify"
      },
      "attrs": ["temperature"]
    },
    "expires": "2025-01-01T00:00:00Z",
    "throttling": 5
  }'

entities: Specifies which entities to monitor.
condition: Specifies the conditions (in this case, changes in the temperature attribute).
notification: Defines where to send the notification (in this case, an HTTP POST to a specified URL).