Skip to content

Commit

Permalink
Event POST example
Browse files Browse the repository at this point in the history
  • Loading branch information
@AndrewDonkin-Gallagher
AndrewDonkin-Gallagher committed Jun 11, 2024
1 parent 2320a63 commit 08271ba
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 13 deletions.
55 changes: 50 additions & 5 deletions ref/events.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ <h5>Schema Definitions</h5>
<a href="#definition-Event-summary"> Event summary </a>
<a href="#definition-Event-detail"> Event detail </a>
<a href="#definition-Event-POST-body"> Event POST body </a>
<a href="#definition-Event-POST-example"> Event POST example </a>
<a href="#definition-Event-groups"> Event groups </a>
<a href="#definition-Divisions"> Divisions </a>
<a href="#definition-Division"> Division </a>
Expand Down Expand Up @@ -176,7 +177,7 @@ <h4 id="alarms-and-events-api-changes-in-920">Alarms and events API changes in 9
</ul>
<h4 id="alarms-and-events-api-changes-in-910">Alarms and events API changes in 9.10</h4>
<ul>
<li>You can request the name of an alarm&#39;s instruction.</li>
<li>You can request the name of an alarm&#39;s instruction, and the contents of the instruction itself.</li>
</ul>
<h4 id="alarms-and-events-api-changes-in-900">Alarms and events API changes in 9.00</h4>
<ul>
Expand All @@ -197,7 +198,7 @@ <h4 id="alarms-and-events-api-changes-in-890">Alarms and events API changes in 8
<p>BREAKING CHANGE: the operator must have the &#39;Create Events and Alarms&#39; privilege in the division of the source item, if your request specifies a source item. Current versions only require that the operator has that privilege on at least one division.</p>
</li>
<li>
<p>To improve the symmetry between events and alarms, they now carry a field <code>eventType</code> containing the ID and name of their type. The <code>type</code> field, which has different contents for alarms and events, is now obsolete (but still supported).</p>
<p>To improve the symmetry between events and alarms, they both now carry a field <code>eventType</code> containing the ID and name of their type. The <code>type</code> field, which has different contents for alarms and events, is now obsolete (but still returned in results).</p>
</li>
<li>
<p>Alarms contain a new field called <code>event</code> containing a link to the corresponding event, mirroring the existing <code>alarm</code> field coming the other way from an event.</p>
Expand Down Expand Up @@ -6810,9 +6811,9 @@ <h2 class="panel-title">
<span class="json-property-required"></span>
</dt>
<dd>
<p>This is a mandatory field in an event. Without it, the POST will fail.</p>
<p>It is mandatory because the server cannot assume a reasonable default. It can for the others.</p>
<p>If your server is running 8.90 or later, <code>eventType</code> is a synonym. If you send both a <code>type</code> block and an <code>eventType</code> block it will use <code>eventType</code>.</p>
<p>A new event must contain either this or (if your server is running 8.90 or later) <code>eventType</code>. Without one of them, the POST will fail.</p>
<p>The event type is mandatory because the server cannot assume a reasonable default. It can for the other fields.</p>
<p>If you send both a <code>type</code> block and an <code>eventType</code> block to a server running 8.90 or later it will use <code>eventType</code>.</p>
</dd>
<dt class="json-inner-schema">
<section class="json-schema-properties">
Expand Down Expand Up @@ -7133,6 +7134,50 @@ <h5>Example</h5>
<span class="hljs-attr">&quot;href&quot;</span>: <span class="hljs-string">&quot;https://localhost:8904/api/doors/745&quot;</span>
}
}
</code></pre> </body>
</html>
<!-- </div> -->
</section>
</div>
</div>
</div>
<div id="definition-Event-POST-example" class="definition panel" data-traverse-target="definition-Event-POST-example">
<h2 class="panel-title">
<a name="/definitions/Event POST example"></a>Event POST example:
<!-- <span class="json-property-type"><span class="json-property-type">object</span>
<span class="json-property-range" title="Value limits"></span>


</span> -->
</h2>
<div class="doc-row">
<div class="doc-copy">
<section class="json-schema-description">
<p>This is an example showing how you could
<a href="#creating-a-new-event">create a new event</a>.</p>
<p>Only <code>eventType</code> is required for the API to accept the POST, but an event is not much without a source item and a message string, and it never hurts to add some details.</p>
<p>See
<a href="#definition-Event-POST-body">the schema definition</a> for a description of each field, and
<a href="#operation--api-events-post">the POST</a> for the rules around event types and items and what happens to your event after you create it.</p>
<p>To make this example work on a server running 8.80 or earlier change <code>eventType</code> to <code>type</code>.</p>
</section>
</div>
<div class="doc-examples">
<section>
<h5>Example</h5>
<!-- <div class="hljs"> -->
<html>
<head></head>
<body><pre><code class="hljs language-json">{
<span class="hljs-attr">&quot;eventType&quot;</span>: {
<span class="hljs-attr">&quot;href&quot;</span>: <span class="hljs-string">&quot;https://localhost:8904/api/events/types/4000&quot;</span>
},
<span class="hljs-attr">&quot;source&quot;</span>: {
<span class="hljs-attr">&quot;href&quot;</span>: <span class="hljs-string">&quot;https://localhost:8904/api/doors/745&quot;</span>
},
<span class="hljs-attr">&quot;message&quot;</span>: <span class="hljs-string">&quot;Glass break detected in southwest sauna&quot;</span>,
<span class="hljs-attr">&quot;details&quot;</span>: <span class="hljs-string">&quot;Temperature dropping&quot;</span>
}
</code></pre> </body>
</html>
<!-- </div> -->
Expand Down
36 changes: 28 additions & 8 deletions swagger/eventsApi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ info:
#### Alarms and events API changes in 9.10
* You can request the name of an alarm's instruction.
* You can request the name of an alarm's instruction, and the contents of the instruction itself.
#### Alarms and events API changes in 9.00
Expand All @@ -73,9 +73,9 @@ info:
Alarms' privilege in the division of the source item, if your request specifies a source item.
Current versions only require that the operator has that privilege on at least one division.
* To improve the symmetry between events and alarms, they now carry a field `eventType`
* To improve the symmetry between events and alarms, they both now carry a field `eventType`
containing the ID and name of their type. The `type` field, which has different
contents for alarms and events, is now obsolete (but still supported).
contents for alarms and events, is now obsolete (but still returned in results).
* Alarms contain a new field called `event` containing a link to the corresponding event,
mirroring the existing `alarm` field coming the other way from an event.
Expand Down Expand Up @@ -2959,13 +2959,14 @@ definitions:
properties:
type:
description: |
This is a mandatory field in an event. Without it, the POST will fail.
A new event must contain either this or (if your server is running 8.90 or later) `eventType`.
Without one of them, the POST will fail.
It is mandatory because the server cannot assume a reasonable default. It can for the
others.
The event type is mandatory because the server cannot assume a reasonable default. It can
for the other fields.
If your server is running 8.90 or later, `eventType` is a synonym. If you send both a `type` block
and an `eventType` block it will use `eventType`.
If you send both a `type` block and an `eventType` block to a server running 8.90 or later
it will use `eventType`.
type: object
properties:
Expand Down Expand Up @@ -3154,6 +3155,25 @@ definitions:
This can be the href of any door your operator can see. Get the href using the
[doors](rest.html#tag-Doors) or [items](#tag-Items) controller.
Event POST example:
required: [type, eventType]
description: |
This is an example showing how you could [create a new event](#creating-a-new-event).
Only `eventType` is required for the API to accept the POST, but an event is not much without
a source item and a message string, and it never hurts to add some details.
See [the schema definition](#definition-Event-POST-body) for a description of each field, and
[the POST](#operation--api-events-post) for the rules around event types and items and what
happens to your event after you create it.
To make this example work on a server running 8.80 or earlier change `eventType` to `type`.
example:
eventType: { "href": "https://localhost:8904/api/events/types/4000" }
source: { "href": "https://localhost:8904/api/doors/745" }
message: "Glass break detected in southwest sauna"
details: "Temperature dropping"

Event groups:
description: Calls to `/api/events/groups/` return this object, which is a named array of groups of event types.
type: object
Expand Down

0 comments on commit 08271ba

Please sign in to comment.