Creating rules from the REST API

You can use the Platform Service HTTP REST API to create and configure rules. Use these rules to send event-driven notifications and to trigger actions.

To use the HTTP REST API, you need to know the following information:

Your organization ID.
When you register with the Platform Service, you are given an organization ID which is a unique six character identifier for your account.
Your API key and authentication token.
You can generate an API key and authentication token by using the dashboard. For more information about API keys and tokens, see API key connection.
The logical interface identifier with which you want to associate the rule To find a logical interface identifier, use the following HTTP REST API:

GET /draft/logicalinterfaces

The following example shows how to use CURL to retrieve information about a logical interface:

curl --request GET \
   --url https://yourOrgID.internetofthings.ibmcloud.com/api/v0002/draft/logicalinterfaces \
   --user '{API Key}:{authorization token}'

The following example shows a response to the GET method:

{
    "results": [
        {
            "id": "5846ed076522050001db0e12",
            "name": "Thermometer Interface",
            "alias": "IThermometer",
            "description": "Thermometer Logical Interface",
            "schemaId": "5846ec826522050001db0e11",
            "version": "draft",
            "created": "2017-06-16T15:41:49Z",
            "createdBy": "a-8x7nmj-9iqt56kfil",
            "updated": "2017-06-16T15:41:49Z",
            "updatedBy": "a-8x7nmj-9iqt56kfil",
            "refs": {
                "schema": "/api/v0002/draft/schemas/5846ec826522050001db0e11",
                "rules": "/api/v0002/draft/logicalinterfaces/5846ed076522050001db0e12/rules"
            }
        }
    ],
    "meta": {
        "total_rows": 1
    }
}

In this example, the logical interface identifier is 5846ed076522050001db0e12.

Configuring rules - scenario

This scenario shows you how to create two rules and is based on the configuration that is created in Scenario: Configuring a common logical interface.

The first rule is called tempRuleMax, which is triggered when a temperature event is received by Platform Service that causes the temperature property of the device state to exceed 44 degrees Celsius. The second rule is called tempRuleMin, which is triggered when a temperature event is received by Platform Service that causes the temperature property of the device state to fall below 10 degrees Celsius.

However, we do not want to hard code the temperature thresholds in the conditions for the rules because this would not allow the thresholds to vary by device instance. Instead, the temperature thresholds are defined as properties on the device metadata and the rule conditions reference these properties using the $instance variable. This scenario uses the tSensor device that was created as part of Scenario: Configuring a common logical interface. This device publishes temperature events that are measured in degrees Celsius. The following metadata is associated with the tSensor device instance:

{
    "tempThresholdMax": 44,
    "tempThresholdMin": 10
}

Tip: Metadata can be added or updated to a device instance after it has been created from the Device Information page of the dashboard. For information about using the dashboard, see Configuring interfaces from the UI.

Complete the following steps to configure the two rules:

Select the logical interface that you want to associate your rule with. In this scenario, we are using the logical interface with the identifier 5846ed076522050001db0e12.
View the current rules that are associated with the logical interface by using the following API:
GET /draft/logicalinterfaces/5846ed076522050001db0e12/rules
As no rules are currently associated with logical interface 5846ed076522050001db0e12, an empty list is returned.

Add a rule called tempRuleMax by using the following API:
POST /draft/logicalinterfaces/5846ed076522050001db0e12/rules
Include the rule name, a condition parameter, and a notification strategy parameter in the body of the request:

 {  
     "name" : "tempRuleMax",
     "condition" : "$state.temperature > $instance.metadata.tempThresholdMax",
     "notificationStrategy": {
         "when": "every-time"
     }
 }

The following example shows the response to the POST method:

 {  
     "name": "tempRuleMax",  
     "id": "5a71991e59080100328710e9",  
     "logicalInterfaceId": "5846ed076522050001db0e12",  
     "condition": "$state.temperature > $instance.metadata.tempThresholdMax",
     "notificationStrategy": {
         "when": "every-time"
     },  
     "version": "draft",  
     "created": "2018-01-31T10:23:26Z",  
     "createdBy": "a-7p9t2v-zsrcacabpa",  
     "updated": "2018-01-31T10:23:26Z",
     "updatedBy": "a-7p9t2v-zsrcacabpa",
     "refs": {  
         "logicalInterface": "/api/v0002/draft/logicalinterfaces/5846ed076522050001db0e12"  
     }
 }

The tempRuleMax rule is triggered if the temperature property on the device state exceeds the value specified in the tempThresholdMax property on the metadata of the tSensor device instance. In our example, the value is 44 degrees Celsius.

Add a rule called tempRuleMin by using the following API:
POST /draft/logicalinterfaces/5846ed076522050001db0e12/rules
Include the rule name, a condition parameter, and a notification strategy parameter in the body of the request:

 {  
     "name" : "tempRuleMin",
     "condition" : "$state.temperature < $instance.metadata.tempThresholdMin",
     "notificationStrategy": {
         "when": "every-time"
     }
 }

The following example shows the response to the POST method:

 {  
     "name": "tempRuleMin",  
     "id": "5a71991e59080100328710e10",  
     "logicalInterfaceId": "5846ed076522050001db0e12",  
     "condition": "$state.temperature < $instance.metadata.tempThresholdMin",
     "notificationStrategy": {
         "when": "every-time"
     },  
     "version": "draft",  
     "created": "2018-01-31T10:23:26Z",  
     "createdBy": "a-7p9t2v-zsrcacabpa",  
     "updated": "2018-01-31T10:23:26Z",  
     "updatedBy": "a-7p9t2v-zsrcacabpa",
     "refs": {  
         "logicalInterface": "/api/v0002/draft/logicalinterfaces/5846ed076522050001db0e12"  
     }
 }

The tempRuleMin rule is triggered if the temperature property on the device state falls below the value specified in the tempThresholdMin property on the metadata of the tSensor device instance. In our example, the value is 10 degrees Celsius.

Validate and activate your configuration by using the activate-configuration operation.
You must activate your configuration after adding a rule, because the action of adding the rule results in a change to the draft model. The activate-configuration operation can be performed on the draft version of the device type or the logical interface. The following example shows a PATCH request where an activate-configuration operation is performed on a draft version of a device type:
```
PATCH /draft/device/types/{typeId}
```
where the payload of the PATCH body contains the following content:
```
 {
     "operation": "activate-configuration"
 }
```
For more information about activating and deactivating your configuration, see Working with logical interfaces.

View the current rules on the active logical interface by using the following API:
GET /logicalinterfaces/5846ed076522050001db0e12/rules
The following example shows a response to the GET method:

 [
     {
         "name": "tempRuleMax",  
         "id": "5a71991e59080100328710e9",
         "logicalInterfaceId": "5846ed076522050001db0e12",
         "condition": "$state.temperature > $instance.metadata.tempThresholdMax",
         "notificationStrategy": {
             "when": "every-time"
         },  
         "version": "active",
         "created": "2018-01-31T10:23:26Z",
         "createdBy": "a-7p9t2v-zsrcacabpa",
         "updated": "2018-01-31T10:23:26Z",
         "updatedBy": "a-7p9t2v-zsrcacabpa",
         "refs": {
             "logicalInterface": "/api/v0002/logicalinterfaces/5846ed076522050001db0e12"
         }
     },
     {
         "name": "tempRuleMin",  
         "id": "5a71561e59055500328710e10",
         "logicalInterfaceId": "5846ed076522050001db0e12",
         "condition": "$state.temperature < $instance.metadata.tempThresholdMin",
         "notificationStrategy": {
             "when": "every-time"
         },  
         "version": "active",
         "created": "2018-01-31T10:23:26Z",
         "createdBy": "a-7p9t2v-zsrcacabpa",
         "updated": "2018-01-31T10:23:26Z",
         "updatedBy": "a-7p9t2v-zsrcacabpa",
         "refs": {
             "logicalInterface": "/api/v0002/logicalinterfaces/5846ed076522050001db0e12"
         }
     }
 ]

For more details about using the API, see the Platform Service HTTP REST API documentation.

Consuming rule notifications.
You can now set up actions or configure your external applications to consume the output of your rule. For information, see Consuming rule notifications.