Publish Events Using POST /record#

Here we’ll use the POST /record endpoint to publish events and we’ll act on the events using a rule.

Publish an Event#

The POST /record endpoint documentation specifies endpoint’s method, path parameters, and query parameters.

Example cURL Command#

Use a cURL command like the one below to publish an example stock bid event.

curl -X POST "https://IEXCLOUDAPPERATE.iex.cloud/v1/record/IEXCLOUDAPPERATE/MY_CUSTOMER_STOCK_BIDS?persist=false&token=YOUR_SECRET_TOKEN" \
	-H 'Content-Type: application/json' \
	-d '[{"account": 1111, "symbol": "MSFT", "bid_price": 250.4, "bid_size": 100}]'

The command publishes an event associated with a schema called MY_CUSTOMER_STOCK_BIDS in the IEXCLOUDAPPERATE workspace. The persist=false query parameter setting informs Apperate to skip writing the data.

The example payload simulates a customer’s stock bid, including the bidding customer’s account number, the stock symbol, the bid price, and the bid size.

HTTP Method:

Here is the endpoint’s HTTP method.

POST /record/:workspace/:id

Path Parameters:

The example command specifies these method path parameter values.

Parameter	Value	Comment
`:workspace`	`IEXCLOUDAPPERATE`	Replace this with your workspace name.
`:id`	`MY_CUSTOMER_STOCK_BIDS`	Enter the name of a schema (new or existing) to associate with your event payload. If you’re persisting payload data to a dataset, specify that dataset’s ID.

Query Parameters:

The example command uses only these non-default query parameter values.

Parameter	Value	Comment
`token`	`YOUR_SECRET_TOKEN`	Required. See Secret API Token.
`persist`	`false`	Default is `true`. If you don’t want to write the payload data to Apperate, set `persist=false`.

The above query parameters are all you need to publish an event.

Note

If you want to persist data (the default behavior), use the duplicateKeyHandling parameter and wait parameter to configure how to handle new records with the same key and whether a response is returned synchronously or asynchronously. See the POST /record reference doc and Write Data in Real Time with POST /record for complete details.

Execute the Command#

Execute the above cURL command, to create your stock bid event and to register your schema with the Rules Engine if it isn’t already registered.

Response:

{"success":true,"message":"wrote 0 records"}

The command registers an event schema successfully without writing records because persist=false.

Verify the Registered Schema#

An easy way to verify schema registration with the Rules Engine is by using a cURL command like the one below to call the GET /rules/schema endpoint.

curl -X GET "https://api.iex.cloud/v1/rules/schema?token=YOUR_SECRET_TOKEN" \
  | jq .schema.workspaces[1].namespaces[0].entities[].entity

It calls the GET /rules/schema endpoint and uses the jq command to list the workspace dataset schemas. Make sure to replace YOUR_SECRET_TOKEN with your value.

Response:

"MY_CUSTOMER_STOCK_BIDS"
// ... more dataset schema names

The workspace dataset entity list includes the event schema.

Note

You can also check dataset schema registrations in the Console, as demonstrated in the next steps.

Create a Rule#

Using the Console, let’s create a rule that triggers when the event bid size is above or equal to 100.

Note

You can just as easily create the following rule using the API. See Create Rules and Alerts Using the API for complete details.

Go to the Console in your browser.
Click Create a Rule in the top left of the navigation tree.

The conditions form appears.

Use Event Facts in Your Conditions#

Create a condition based on facts from the dataset schema entity you registered.

Specify the bid_size column must be above or equal to 100.

When you’re done setting conditions, advance to the rule outputs page.

Set the Output#

Configure your Alert Details and any Additional Indexes you want. For this example, we’ll include all the other column values in the output.

Here’s what it looks like after adding all the columns to the output.

When you’re done with the outputs, advance to the rule summary page. The rule summary page appears.

Review Your Rule#

In the rule summary page, name your rule. When you’re done, click Create to create and activate your rule. Your rule appears in the Rules page.

Let’s test the rule with an event.

Trigger the Rule Using a POST /record Event#

You can publish a new event using your previous POST /record cURL command or using it with a different payload. Here’s the command with new payload values.

curl -X POST "https://IEXCLOUDAPPERATE.iex.cloud/v1/record/IEXCLOUDAPPERATE/MY_CUSTOMER_STOCK_BIDS?persist=false&token=YOUR_SECRET_TOKEN" \
	-H 'Content-Type: application/json' \
	-d '[{"account": 3333, "symbol": "AAPL", "bid_price": 160.4, "bid_size": 200}]'

Important

Make sure to specify the dataset ID you’re filtering on as the id path parameter value in your POST /record call.

Verify that the event passes your rule.

Verify the rule sends the event index and additional indexes to your output destination. Here’s an email message with the event output.

Note

The rule sends an alert after the alert wait time you configured.

Congratulations on publishing custom events to Apperate!

Conclusion#

Now that you know how to create events, you can create events based on any kind of data you want.

If you’re developing in JavaScript, you can use our apperate.write() JavaScript method to publish events.