From d4159dc73d2bd92c0ba4fae1bd2fd98f231c224d Mon Sep 17 00:00:00 2001 From: waldek Date: Mon, 24 Mar 2025 12:57:19 +0000 Subject: [PATCH 1/3] AB#10424 update docs with events /search endpoint --- .../api-reference/events-api/index.md | 111 +++++++++++++++++- 1 file changed, 107 insertions(+), 4 deletions(-) diff --git a/content/developers/api-reference/events-api/index.md b/content/developers/api-reference/events-api/index.md index 1bd8447b4..3e9befee1 100644 --- a/content/developers/api-reference/events-api/index.md +++ b/content/developers/api-reference/events-api/index.md @@ -95,10 +95,7 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor 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/` -{{< note >}} -**Note:** The current preview limits fetching Events to the Event identity. -Querying across event attributes and trails are coming in a future preview. -{{< /note >}} + #### Fetch Events by Identity @@ -116,6 +113,112 @@ Querying across event attributes and trails are coming in a future preview. "https://app.datatrails.ai/archivist/v1/events/$EVENT_ID" | jq ``` + + +#### Fetch Multiple Events + +- To fetch multiple events use a search document and post it to Events Search endpoint + Search document has following form: + + ```json + { + "filter": "", + "top": 10, + "skip": 0, + } + ``` + +{{< note >}} +**Note:** The current preview does not support filtering of Events. +Filtering across event attributes and trails are coming in a future preview. +{{< /note >}} + + where top indicates number of results to return (max. 50) and skip indicates how many results to skip over before retruning set of results. + + Response will be a list of events matching above criteria: + + ```json + { + "events": [ + { + "identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "attributes": { + "inspector": "Clouseau", + "arc_display_type": "Safety Conformance", + "Safety Rating": "90" + }, + "trails": [ + "Safety Conformance", + "Clouseau" + ], + "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_at": 1736421833577, + "confirmation_status": "STORED", + "merklelog_commit": { + "index": "0", + "idtimestamp": "" + } + }, + { + "identity": "events/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", + "attributes": { + "inspector": "Clouseau", + "arc_display_type": "Safety Conformance", + "Safety Rating": "99" + }, + "trails": [ + "Safety Conformance", + "Clouseau" + ], + "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_at": 1736421873579, + "confirmation_status": "STORED", + "merklelog_commit": { + "index": "0", + "idtimestamp": "" + } + } + ], + } + ``` + + 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 sumply re-issue `/search` request with skip increased by number of results in current response. + +- To fetch all Event records, simply create search document and save to a file `search.json`: + + ```json + { + "filter": "", + "top": 10, + "skip": 0, + } + ``` + + and `POST` it to Search endpoint: + + ```bash + curl -X POST \ + -H "@$HOME/.datatrails/bearer-token.txt" \ + -d @$HOME/search.json \ + "https://app.datatrails.ai/archivist/v1/events/search" \ + | jq + ``` + + if `x-total-count` response header has value greater than 10 (as indicated by value of `top` in `search.json`) modify `serch.json` to to following: + + ```json + { + "filter": "", + "top": 10, + "skip": 10, + } + ``` + + and `POST` to the same nedpoint again to retrieve second page of results, and repeat this process until `skip` + numer or results in response is equal `x-total-count`. + + ## Events OpenAPI Docs {{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/events.swagger.json" >}} From c3956c73f3577023ba1b917a41fb65982856c614 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Wed, 26 Mar 2025 22:28:26 +0200 Subject: [PATCH 2/3] spelling and formatting Signed-off-by: steve lasker --- .../api-reference/events-api/index.md | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/content/developers/api-reference/events-api/index.md b/content/developers/api-reference/events-api/index.md index 3e9befee1..4973f604e 100644 --- a/content/developers/api-reference/events-api/index.md +++ b/content/developers/api-reference/events-api/index.md @@ -31,12 +31,6 @@ To minimize the impact, prior to switching to Asset-free Events, it is recommend ## Events API Examples -{{< note >}} -**Note:** If you are looking for a simple way to test DataTrails APIs you might prefer the [Postman collection](https://www.postman.com/datatrails-inc/workspace/datatrails-public/overview), the [YAML runner](/developers/yaml-reference/story-runner-components/) or the [Developers](https://app.datatrails.ai) section of the web UI. - -Additional YAML examples can be found in the articles in the [Overview](/platform/overview/introduction/) section. -{{< /note >}} - ### Event Creation - Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions. @@ -95,8 +89,6 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor 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/` - - #### Fetch Events by Identity - Replace the `` below, using the event-id from the created event above: `"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`: @@ -113,19 +105,19 @@ Event records in DataTrails are assigned UUIDs at creation time and referred to "https://app.datatrails.ai/archivist/v1/events/$EVENT_ID" | jq ``` - - #### Fetch Multiple Events - To fetch multiple events use a search document and post it to Events Search endpoint Search document has following form: - ```json + ```bash + cat > /tmp/search.json <}} @@ -133,7 +125,7 @@ Event records in DataTrails are assigned UUIDs at creation time and referred to Filtering across event attributes and trails are coming in a future preview. {{< /note >}} - where top indicates number of results to return (max. 50) and skip indicates how many results to skip over before retruning set of results. + where top indicates number of results to return (max. 50) and skip indicates how many results to skip over before returning set of results. Response will be a list of events matching above criteria: @@ -184,40 +176,50 @@ Filtering across event attributes and trails are coming in a future preview. } ``` - 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 sumply re-issue `/search` request with skip increased by number of results in current response. + 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. - To fetch all Event records, simply create search document and save to a file `search.json`: - ```json + ```bash + cat > /tmp/search.json < /tmp/search.json < Date: Fri, 28 Mar 2025 12:09:44 +0200 Subject: [PATCH 3/3] Complete formatting and examples for baseline filtering and paging of events Signed-off-by: steve lasker --- .../api-reference/events-api/index.md | 189 +++++++++--------- 1 file changed, 93 insertions(+), 96 deletions(-) diff --git a/content/developers/api-reference/events-api/index.md b/content/developers/api-reference/events-api/index.md index 4973f604e..7314820f2 100644 --- a/content/developers/api-reference/events-api/index.md +++ b/content/developers/api-reference/events-api/index.md @@ -89,9 +89,11 @@ To minimize the impact, prior to switching to Asset-free Events, it is recommend 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/` -#### Fetch Events by Identity +## Fetch Events by Identity -- Replace the `` below, using the event-id from the created event above: `"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`: +- Replace the `` below, using the event-id from the created event above. + `"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`: + Note, "`events/`" must be included as it's part of the resource name: ```bash EVENT_ID= @@ -102,129 +104,124 @@ Event records in DataTrails are assigned UUIDs at creation time and referred to ```bash curl -X GET \ -H "@$HOME/.datatrails/bearer-token.txt" \ - "https://app.datatrails.ai/archivist/v1/events/$EVENT_ID" | jq + "https://app.datatrails.ai/archivist/v1/$EVENT_ID" | jq ``` -#### Fetch Multiple Events +## Filtering and Paging Events -- To fetch multiple events use a search document and post it to Events Search endpoint +- To fetch multiple events, use a search document, posting to the `/events/search` endpoint Search document has following form: ```bash cat > /tmp/search.json <}} -**Note:** The current preview does not support filtering of Events. -Filtering across event attributes and trails are coming in a future preview. -{{< /note >}} - - where top indicates number of results to return (max. 50) and skip indicates how many results to skip over before returning set of results. - - Response will be a list of events matching above criteria: - - ```json - { - "events": [ - { - "identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "attributes": { - "inspector": "Clouseau", - "arc_display_type": "Safety Conformance", - "Safety Rating": "90" + where: + `filter` = attribute name/value pairs + `top` = number of results to return (max. 50) and + `skip` = how many results to skip over before returning set of results + + {{< note >}} + **Note:** The current preview does not support filtering of Events. + Filtering across event attributes and trails are coming in a future preview. + {{< /note >}} + + - Post `search.json` to the `/search` endpoint: + + ```bash + curl -X POST \ + -H "@$HOME/.datatrails/bearer-token.txt" \ + -d "@/tmp/search.json" \ + "https://app.datatrails.ai/archivist/v1/events/search" \ + | jq + ``` + + - The response will include a list of events matching above criteria: + + ```json + { + "events": [ + { + "identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "attributes": { + "inspector": "Clouseau", + "arc_display_type": "Safety Conformance", + "Safety Rating": "90" + }, + "trails": [ + "Safety Conformance", + "Clouseau" + ], + "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_at": 1736421833577, + "confirmation_status": "STORED", + "merklelog_commit": { + "index": "0", + "idtimestamp": "" + } }, - "trails": [ - "Safety Conformance", - "Clouseau" - ], - "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "created_at": 1736421833577, - "confirmation_status": "STORED", - "merklelog_commit": { - "index": "0", - "idtimestamp": "" + { + "identity": "events/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", + "attributes": { + "inspector": "Clouseau", + "arc_display_type": "Safety Conformance", + "Safety Rating": "99" + }, + "trails": [ + "Safety Conformance", + "Clouseau" + ], + "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "created_at": 1736421873579, + "confirmation_status": "STORED", + "merklelog_commit": { + "index": "0", + "idtimestamp": "" + } } - }, - { - "identity": "events/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", - "attributes": { - "inspector": "Clouseau", - "arc_display_type": "Safety Conformance", - "Safety Rating": "99" - }, - "trails": [ - "Safety Conformance", - "Clouseau" - ], - "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "created_at": 1736421873579, - "confirmation_status": "STORED", - "merklelog_commit": { - "index": "0", - "idtimestamp": "" - } - } - ], - } - ``` - - 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. - -- To fetch all Event records, simply create search document and save to a file `search.json`: - - ```bash - cat > /tmp/search.json < /tmp/search.json <}} + ```bash + curl -X POST \ + -H "@$HOME/.datatrails/bearer-token.txt" \ + -d /tmp/search.json \ + "https://app.datatrails.ai/archivist/v1/events/search" \ + | jq + ``` ## Integrity Protecting Content Integrity protected content can be hashed within an Event using the [Attachments API](/developers/api-reference/attachments-api/). + +## Events OpenAPI Docs + +{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/events.swagger.json" >}}