Managing Rules Using the API#
You can create and manage your rules using the Rules API. Here we’ll demonstrate …
Listing rules
Getting a specific rule
Pausing and resuming rule activity
Deleting a rule
Important
All the Rules API requests require your Secret API Token.
Listing Rules#
The GET /rules endpoint is great place to browse all your rules. Here’s an example request and response.
Request:
curl -X GET "https://api.iex.cloud/v1/rules?token=YOUR_SECRET_TOKEN"
Response:
[
{
"id": "d673e169-da24-48cb-b168-0a12e56bf915",
"name": "Rule 68",
"dateCreated": "2023-02-27",
"dateUpdated": "2023-02-27",
"isActive": false,
"ran": "543923",
"passed": "484607",
"sent": "52",
"failed": "59316",
"evaluated": "1677515098059"
},
{
"id": "6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e",
"name": "client 1",
"dateCreated": "2023-02-21",
"dateUpdated": "2023-02-21",
"isActive": true,
"ran": 0,
"passed": 0,
"sent": 0,
"failed": 0,
"evaluated": 0
}//, more rules ...
]
The response includes an object for each rule. Management activities like pausing, un-pausing, and deleting a rule require the rule’s id. You can get a rule’s id from the GET /rules response or from the Rules dashboard in the console.
Let’s get a specific rule using a rule’s id.
Getting a Rule#
The following request to the GET /rules/info/:id endpoint gets information on one of the rules returned in the response from GET /rules in the previous section.
Request:
curl -X GET "https://api.iex.cloud/v1/rules/info/6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e?token=YOUR_TOKEN"
Response:
[
{
"id": "6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e",
"name": "client 1",
"dateCreated": "2023-02-21",
"dateUpdated": "2023-02-21",
"isActive": true,
"ran": 0,
"passed": 0,
"sent": 0,
"failed": 0,
"evaluated": 0
}
]
If the isActive value is true, the rule is running. Otherwise, it’s paused. You may want to pause a rule before editing it.
Let’s pause this active rule.
Pausing a Rule#
You can pause a running rule by calling the POST /rules/pause/:ruleId endpoint. You pass your secret token and the rule ID as POST parameters in a JSON object.
Here’s an example request that pauses the rule from the previous step.
Request:
"use strict";
const Request = require("request-promise-native");
function connect() {
Request({
method: "POST",
url: "https://api.iex.cloud/v1/rules/pause/6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e",
json: {
token: "YOUR_SECRET_TOKEN"
},
}).then((body) => {
console.log(body);
}).catch((err) => {
console.log("Error in request", err);
});
}
connect();
Response:
true
The rule is disabled. Let’s update the rule while it’s paused.
Note
You can update a rule while it’s active.
Updating a Rule#
You can change a rule’s attributes and behavior by using the POST /rules/create endpoint.
Here’s what’s required:
Set the
ruleIdparameter to the existing rule’sid. You can get this from theGET /rulesendpoint response or from the Console–to copy the rule’s ID, click on it in the Rules list.Set all the
POST /rules/createendpoint’s Required post parameters–you can set them to new values or to existing values.
Optionally, you can specify any of the other parameters to change their values.
Below is an example rule update request and response.
Request:
'use strict';
const Request = require('request-promise-native');
function connect() {
Request({
method: 'POST',
url: 'https://api.iex.cloud/v1/rules/create',
json: {
token: 'YOUR_SECRET_TOKEN',
ruleId: "6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e",
ruleName: "My Rule",
type: "any",
index: [ "CORE:STOCK:AAPL:low" ],
conditions: [
["$index[0]",">",100],
],
outputs: [
{
frequency: 60*60,
method: 'email',
to: 'person@company.com'
}
]
},
}).then((body) => {
console.log(body);
}).catch((err) => {
console.log("Error in request", err);
});
}
connect();
Response:
{ id: 'f759e05a-7cda-44cc-9579-41178249be4a', weight: 0 }
You can check for your rule changes and resulting side effects in the Console and in their output targets.
Unpausing a Rule#
Unpausing a rule enables it to resume activity. You can unpause a rule by calling the POST /rules/resume/:ruleId endpoint. You pass your secret token and the rule ID as POST parameters in a JSON object.
Request:
"use strict";
const Request = require("request-promise-native");
function connect() {
Request({
method: "POST",
url: "https://api.iex.cloud/v1/rules/resume/6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e",
json: {
token: "YOUR_SECRET_TOKEN"
},
}).then((body) => {
console.log(body);
}).catch((err) => {
console.log("Error in request", err);
});
}
connect();
Response:
true
On successfully unpausing the rule, the endpoint returns true.
Deleting a Rule#
You can delete a rule by calling the DELETE /rules/:id endpoint. The following request deletes the example rule we’ve been working with.
Request:
curl -X DELETE "https://api.iex.cloud/v1/rules/6ca3b2b4-13c7-4bfb-97c4-516da23fbd2e?token=YOUR_SECRET_TOKEN"
Response:
true
The rule is removed.
Conclusion#
Now you know how to use the Rules API to list all your rules, get a rule, pause a rule, unpause a rule, and delete a rule. You’re off to a great start managing your rules!
Hint
You can also manage rules in the Console.