ATL-674:- Add SHIELD telemetry event API endpoints - #202
Conversation
Introduces SHIELD telemetry event support in the Data Gateway OpenAPI spec, including new event schemas, event-name enum values, and endpoints to create events plus list events globally or by tenant with optional date filtering. Also bumps the API and TypeScript SDK package versions to 3.3.4 to publish the new contract.
There was a problem hiding this comment.
Pull request overview
Adds SHIELD telemetry “event” support to the Data Gateway OpenAPI spec (new schemas + endpoints) and bumps the generated TypeScript SDK version to match the updated API surface.
Changes:
- Added
Telemetry.Shield.EventNameenum andTelemetry.Shield.Eventschema definitions. - Added
/Api/Telemetry/Shield/Event(POST/GET) and/Api/Telemetry/Shield/Event/Tenant/{tenantId}(GET) endpoints to the OpenAPI spec. - Bumped Data Gateway spec + TypeScript SDK versions to
3.3.4.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| src/dataGateway/TypeScript/package.json | Bumps SDK package version to 3.3.4. |
| src/dataGateway/TypeScript/package-lock.json | Keeps lockfile version in sync with the SDK bump to 3.3.4. |
| specs/Data-Gateway.json | Adds SHIELD telemetry event schemas/endpoints and updates spec version to 3.3.4. |
Files not reviewed (1)
- src/dataGateway/TypeScript/package-lock.json: Generated file
Suppressed comments (1)
specs/Data-Gateway.json:8131
- The POST request body schema references
Telemetry.Shield.Event, which also includeseventId,tenantId, and timestamps. Even if the service ignores them, the contract currently suggests clients can submit these fields, which risks tenant spoofing/misuse and generates misleading SDK types. Use an input schema that only acceptseventName.
"schema": {
"$ref": "#/components/schemas/Telemetry.Shield.Event"
}
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Marks SHIELD event identifiers and timestamps as read-only in the OpenAPI schema. Updates the GET endpoint permission text to reflect the required Telemetry.Shield.Read.All and Telemetry.Shield.ReadWrite.All scopes, and adjusts the spec version metadata accordingly.
This change updates the Data Gateway schema descriptions for SHIELD event types and records to make the wording more concise and consistent. It removes redundant 'telemetry' phrasing and clarifies that the eventId uniquely identifies the event itself.
Update the Data Gateway OpenAPI specification and TypeScript SDK package metadata to version 3.4.0, keeping the published API version and generated package artifacts in sync.
Pasha Zayko (pasha-zayko)
left a comment
Pasha Zayko (pasha-zayko)
left a comment
There was a problem hiding this comment.
A couple of small changes and we can publish this
| "400": { | ||
| "$ref": "#/components/responses/400" | ||
| }, | ||
| "401": { |
There was a problem hiding this comment.
I do not see code where it returns 401 or 403 - unless you plan to use them, which is acceptable, lets not confuse the behavior with unavailable/unplanned capabilities
There was a problem hiding this comment.
I checked the existing middleware behaviour, and it looks like both 401 and 403 responses are already possible for this endpoint:
401 Unauthorized can be returned by the global clientAuthorization middleware when the bearer token is missing or malformed.
403 Forbidden can be returned by the scope enforcement middleware when the caller is authenticated but does not have the required telemetryShieldReadWrite permissions.
My intention was to document the endpoint's actual behaviour rather than introduce new functionality. That said, I'm happy to remove them from the documentation if you'd prefer to keep it focused on the endpoint-specific responses only.
For example, I called the endpoint with an invalid token and received the following response.
And this response was generated by the code in "bearerAuthentication.ts."
| "400": { | ||
| "$ref": "#/components/responses/400" | ||
| }, | ||
| "401": { |
There was a problem hiding this comment.
Same as earlier, 401 and 403 are not response codes known in the code currently
There was a problem hiding this comment.
Same as above.
| "400": { | ||
| "$ref": "#/components/responses/400" | ||
| }, | ||
| "401": { |
There was a problem hiding this comment.
Same as earlier, 401 and 403 are not response codes known in the code currently
There was a problem hiding this comment.
Same as above
This change adds example payloads for Shield event arrays in the Data-Gateway OpenAPI spec. The examples illustrate common event lifecycle entries such as installation and license report progress, improving discoverability and documentation for API consumers.
This pull request adds new telemetry support for SHIELD events to the Data Gateway API and updates the SDK version to 3.4.0. The main changes include new API endpoints for submitting and retrieving SHIELD event records, new schema definitions for telemetry events, and version updates in the OpenAPI spec and TypeScript SDK package files.
Telemetry SHIELD Event API additions:
/Api/Telemetry/Shield/Eventendpoint for creating (POST) and listing (GET) SHIELD telemetry events across all tenants, including request/response schemas and permission requirements./Api/Telemetry/Shield/Event/Tenant/{tenantId}endpoint for retrieving SHIELD event records for a specific tenant, with filtering and security details.Schema and specification updates:
Telemetry.Shield.EventNameenum andTelemetry.Shield.Eventobject schema to define SHIELD event names and event structure, including example data.3.3.1to3.4.0inspecs/Data-Gateway.json.SDK version bump:
3.4.0in bothpackage.jsonandpackage-lock.jsonto reflect the new API additions. [1] [2]