Skip to content

Commit 33ba4e2

Browse files
SteveLaskerSteveLasker
committed
Complete formatting and examples for baseline filtering and paging of events
Signed-off-by: steve lasker <stevenlasker@hotmail.com>
1 parent c3956c7 commit 33ba4e2

1 file changed

Lines changed: 93 additions & 96 deletions

File tree

  • content/developers/api-reference/events-api

‎content/developers/api-reference/events-api/index.md‎

Lines changed: 93 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -89,9 +89,11 @@ To minimize the impact, prior to switching to Asset-free Events, it is recommend
8989
9090
Event records in DataTrails are assigned UUIDs at creation time and referred to in all future API calls by a their unique identity in the format: `events/<event-id>`
9191
92-
#### Fetch Events by Identity
92+
## Fetch Events by Identity
9393
94-
- Replace the `<event-id>` below, using the event-id from the created event above: `"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`:
94+
- Replace the `<event-id>` below, using the event-id from the created event above.
95+
`"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`:
96+
Note, "`events/`" must be included as it's part of the resource name:
9597
9698
```bash
9799
EVENT_ID=<event-id>
@@ -102,129 +104,124 @@ Event records in DataTrails are assigned UUIDs at creation time and referred to
102104
```bash
103105
curl -X GET \
104106
-H "@$HOME/.datatrails/bearer-token.txt" \
105-
"https://app.datatrails.ai/archivist/v1/events/$EVENT_ID" | jq
107+
"https://app.datatrails.ai/archivist/v1/$EVENT_ID" | jq
106108
```
107109
108-
#### Fetch Multiple Events
110+
## Filtering and Paging Events
109111
110-
- To fetch multiple events use a search document and post it to Events Search endpoint
112+
- To fetch multiple events, use a search document, posting to the `/events/search` endpoint
111113
Search document has following form:
112114
113115
```bash
114116
cat > /tmp/search.json <<EOF
115117
{
116118
"filter": "",
117-
"top": 10,
119+
"top": 20,
118120
"skip": 0
119121
}
120122
EOF
121123
```
122124
123-
{{< note >}}
124-
**Note:** The current preview does not support filtering of Events.
125-
Filtering across event attributes and trails are coming in a future preview.
126-
{{< /note >}}
127-
128-
where top indicates number of results to return (max. 50) and skip indicates how many results to skip over before returning set of results.
129-
130-
Response will be a list of events matching above criteria:
131-
132-
```json
133-
{
134-
"events": [
135-
{
136-
"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
137-
"attributes": {
138-
"inspector": "Clouseau",
139-
"arc_display_type": "Safety Conformance",
140-
"Safety Rating": "90"
125+
where:
126+
`filter` = attribute name/value pairs
127+
`top` = number of results to return (max. 50) and
128+
`skip` = how many results to skip over before returning set of results
129+
130+
{{< note >}}
131+
**Note:** The current preview does not support filtering of Events.
132+
Filtering across event attributes and trails are coming in a future preview.
133+
{{< /note >}}
134+
135+
- Post `search.json` to the `/search` endpoint:
136+
137+
```bash
138+
curl -X POST \
139+
-H "@$HOME/.datatrails/bearer-token.txt" \
140+
-d "@/tmp/search.json" \
141+
"https://app.datatrails.ai/archivist/v1/events/search" \
142+
| jq
143+
```
144+
145+
- The response will include a list of events matching above criteria:
146+
147+
```json
148+
{
149+
"events": [
150+
{
151+
"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
152+
"attributes": {
153+
"inspector": "Clouseau",
154+
"arc_display_type": "Safety Conformance",
155+
"Safety Rating": "90"
156+
},
157+
"trails": [
158+
"Safety Conformance",
159+
"Clouseau"
160+
],
161+
"origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
162+
"created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
163+
"created_at": 1736421833577,
164+
"confirmation_status": "STORED",
165+
"merklelog_commit": {
166+
"index": "0",
167+
"idtimestamp": ""
168+
}
141169
},
142-
"trails": [
143-
"Safety Conformance",
144-
"Clouseau"
145-
],
146-
"origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
147-
"created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
148-
"created_at": 1736421833577,
149-
"confirmation_status": "STORED",
150-
"merklelog_commit": {
151-
"index": "0",
152-
"idtimestamp": ""
170+
{
171+
"identity": "events/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
172+
"attributes": {
173+
"inspector": "Clouseau",
174+
"arc_display_type": "Safety Conformance",
175+
"Safety Rating": "99"
176+
},
177+
"trails": [
178+
"Safety Conformance",
179+
"Clouseau"
180+
],
181+
"origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
182+
"created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
183+
"created_at": 1736421873579,
184+
"confirmation_status": "STORED",
185+
"merklelog_commit": {
186+
"index": "0",
187+
"idtimestamp": ""
188+
}
153189
}
154-
},
155-
{
156-
"identity": "events/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
157-
"attributes": {
158-
"inspector": "Clouseau",
159-
"arc_display_type": "Safety Conformance",
160-
"Safety Rating": "99"
161-
},
162-
"trails": [
163-
"Safety Conformance",
164-
"Clouseau"
165-
],
166-
"origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
167-
"created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
168-
"created_at": 1736421873579,
169-
"confirmation_status": "STORED",
170-
"merklelog_commit": {
171-
"index": "0",
172-
"idtimestamp": ""
173-
}
174-
}
175-
],
176-
}
177-
```
178-
179-
Use `top` and `skip` alongside `x-total-count` response header to navigate results. If sum of `skip` and number of results in response is less than the count of all results (this will be returned in `x-total-count` response header) there is more results to retrieve, to get next set of results sImply re-issue `/search` request with skip increased by number of results in current response.
180-
181-
- To fetch all Event records, simply create search document and save to a file `search.json`:
182-
183-
```bash
184-
cat > /tmp/search.json <<EOF
185-
{
186-
"filter": "",
187-
"top": 10,
188-
"skip": 0,
189-
}
190-
EOF
191-
```
190+
]
191+
}
192+
```
192193
193-
Then `POST` `search.json` to the Search endpoint:
194+
### Fetch Paged Results
194195
195-
```bash
196-
curl -X POST \
197-
-H "@$HOME/.datatrails/bearer-token.txt" \
198-
-d /tmp/search.json \
199-
"https://app.datatrails.ai/archivist/v1/events/search" \
200-
| jq
201-
```
196+
Use `top` and `skip` alongside `x-total-count` response header to navigate results.
197+
If sum of `skip` and number of results in response is less than the count of all results (`x-total-count` in the response header) there are more results to retrieve.
198+
To get the next set of results, re-issue the `/search` request with `skip` increased by number of results in current response.
202199
203-
If `x-total-count` response header has value greater than 10 (as indicated by value of `top` in `search.json`) modify `search.json` to the following:
200+
If `x-total-count` response header has value greater than 2 (as indicated by value of `top` in `search.json`) modify `search.json` to the following:
204201
205202
```bash
206203
cat > /tmp/search.json <<EOF
207204
{
208205
"filter": "",
209-
"top": 10,
210-
"skip": 10,
206+
"top": 2,
207+
"skip": 2
211208
EOF
212209
```
213210
214-
and `POST` to the same endpoint again to retrieve second page of results, and repeat this process until `skip` + number or results in response is equal `x-total-count`.
215-
216-
```bash
217-
curl -X POST \
218-
-H "@$HOME/.datatrails/bearer-token.txt" \
219-
-d /tmp/search.json \
220-
"https://app.datatrails.ai/archivist/v1/events/search" \
221-
| jq
222-
```
223-
224-
## Events OpenAPI Docs
211+
- Post to the `/events/search/` endpoint to retrieve another page of results, repeating this process until `skip` + number or results in the response is equal to `x-total-count`.
225212
226-
{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/events.swagger.json" >}}
213+
```bash
214+
curl -X POST \
215+
-H "@$HOME/.datatrails/bearer-token.txt" \
216+
-d /tmp/search.json \
217+
"https://app.datatrails.ai/archivist/v1/events/search" \
218+
| jq
219+
```
227220
228221
## Integrity Protecting Content
229222
230223
Integrity protected content can be hashed within an Event using the [Attachments API](/developers/api-reference/attachments-api/).
224+
225+
## Events OpenAPI Docs
226+
227+
{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/events.swagger.json" >}}

0 commit comments

Comments
 (0)