Lab 981 describe new v1 architecture report endpoints in open api#77
Conversation
|
No dependency changes detected. Learn more about Socket for GitHub. 👍 No dependency changes detected in pull request |
There was a problem hiding this comment.
Pull request overview
This pull request introduces new remediation capabilities to the SHIELD API by adding endpoints for performing remediation actions and managing break glass security groups. The changes include updates to both the OpenAPI specification and the TypeScript SDK package version.
Key Changes:
- Added new
/Api/Deploy/RemediatePOST endpoint for performing security remediation steps - Added
/Api/Deploy/Remediate/BreakGlassGET and POST endpoints for managing break glass security groups - Enhanced configuration item schema with
deployStateproperty to track deployment status - Added
operationquery parameter to the deploy progress endpoint to distinguish between deploy and remediate operations
Reviewed changes
Copilot reviewed 2 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/shield/TypeScript/package.json | Bumped package version from 3.0.10 to 3.0.11 |
| src/shield/TypeScript/package-lock.json | Updated lockfile to reflect new package version and removed/updated various dependency metadata |
| specs/SHIELD.json | Added remediation endpoints, enhanced configuration item schema with deployState, added operation parameter, updated API version to 3.0.9 |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "enum": [ | ||
| "notDeployed", | ||
| "deployed", | ||
| "Mutated", |
There was a problem hiding this comment.
The enum value "Mutated" has inconsistent capitalization compared to other enum values ("notDeployed", "deployed", "error"). For consistency, this should be "mutated" (lowercase).
| "Mutated", | |
| "mutated", |
There was a problem hiding this comment.
Copilot wasn't able to review any files in this pull request.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Introduces the ArchitectureReportV1 schema, supporting objects, and new API endpoints for submitting, retrieving, and deleting architecture reports and correlation records. Also adds the 'Architecture Reporting' tag to the API documentation.
Replaces 'example' fields with 'examples' arrays for multiple schema objects to improve consistency and support OpenAPI standards. Also adds new CommonPrincipalAssignment, DevicePrincipalAssignment, and UserPrincipalAssignment schema definitions.
***WIP*** Replaces inline definitions of LicenseReport.CorrelationRecord and CorrelationRecordV0 with references to Report.CorrelationRecordV0. Updates references and descriptions for principal data and correlation records in architecture and report schemas for consistency. Also renames CommonPrincipalAssignment to Report.CommonPrincipalAssignment and updates related references.
Refined operationId naming for clarity and consistency across endpoints. Enhanced endpoint descriptions with permission and access details. Added 401 and 403 error responses to relevant endpoints. Updated schema references and parameter lists for improved accuracy.
Replaces various 401, 403, and 404 error responses with a unified 500 Internal Server Error response across multiple endpoints in Data-Gateway.json. Adds a description for the 500 error and changes some success response codes from 201 to 200 for consistency.
Updated the Data-Gateway JSON schema to clarify and expand user and device principal records, including required fields and more detailed property definitions. Enhanced the structure and examples for inferred attributes and enhanced identity data, added explicit nullability, and improved descriptions for service plan and license references. These changes improve schema accuracy and documentation for integrators.
Updated the descriptions for the POST and GET /Api/V1/ArchitectureReport endpoints to specify required scopes and tenant access restrictions for improved API documentation clarity.
Updated required fields and descriptions for user and device principal records, improved enhanced identity data structure to support consent-based nullability, and clarified examples and titles for correlation and principal metadata records. These changes improve schema clarity, flexibility, and alignment with consent requirements.
Updated all references of LicenseReport, LicenseReport.CorrelationRecord, and LicenseReport.LicenseData to LicenseReportV0, LicenseReportV0.CorrelationRecord, and LicenseReportV0.LicenseData in Data-Gateway.json. This change clarifies schema versioning and improves maintainability.
Added detailed example objects for Architecture Report endpoints and correlation records, updated required fields in the correlation record schema, and removed unused principal assignment schemas. Also moved and clarified endpoint summaries for improved OpenAPI documentation consistency.
Reduced the required fields in the 'Report - Correlation Record V1' schema to only 'auditTenantAccount'. Updated example objects to match the new schema requirements by removing other previously required fields. Jagdish helped :)
dontPushTheButton
force-pushed
the
LAB-981_describe-new-v1-ArchitectureReport-endpoints-in-OpenApi
branch
from
ac34733 to
7888615
Compare
pasha-zayko
left a comment
pasha-zayko
left a comment
There was a problem hiding this comment.
There are several minor items to adjust.
The general concern I see is the inconsistency of applying versioning across changes to License Report. There should be matching change to introduce generic schemas for LicenseReportV1 as were done to LicenseReportV0 - currently missing LicenseReportV1.CorrelationRecord, or should change that LicenseReportV0.CorrelationRecord is not present and just use Report.CorrelationRecord(V0/V1) directly.
As such, ArchitectureReportV1.CorrelationRecord appears to be either alone or not needed.
The versioning is tricky. I'm not the biggest fan of the way we are doing it in the Data Gateway api, but I'm happy to do it the way we are. Jagdish and I were trying to set up the OpenApi inheritance to mirror the api. Ultimately in the api, all reports versions increment every time any group of report types (or CorrelationRecord type) is updated. In this case, we initially had LicenseReport and CorrelationRecord. Then, we added LicenseReportV1, ArchitectureReportV1 and CorrelationRecordV1. At the same time, we changed the existing types to be versioned: LicenseReport -> LicenseReportV0 and CorrelationRecord -> CorrelationRecordV0. Then we set up some type aliases such that the unversioned types are always the latest version. The biggest reason I don't like this is that the unversioned end points (only relevant for the license report) are used for manipulating the V0 license reports. This is temporary though. As we keep versioning reports, eventually the older versions will be removed, and we don't have to worry about it. Complicating this a little further is that even though each report type's correlation records are stored in different tables each table will have the exact same structure. The main reason I added the report specific schemas that inherit a common schema was to have different descriptions on each schema, but if we make the common schemas description general enough to be used in both places, we can skip the inheritance and refence the common schema directly in both places. That might be simplest. What are your thoughts? |
Added 'schemaVersion' field to ArchitectureReportV1.TenantMetadata and updated its title. Revised several endpoint descriptions to refer to 'architecture report' instead of 'license report'. Standardized operationId path parameters to use colon notation for consistency.
- Eliminated duplicate LicenseReportV0.CorrelationRecord and ArchitectureReportV1.CorrelationRecord schema definitions. - Updated all references to use the shared Report.CorrelationRecordV0 and Report.CorrelationRecordV1 schemas directly for consistency and maintainability.
Updated the Data-Gateway.json specification to include 'schemaVersion' as a required field alongside 'correlation', 'tenantMetadata', and 'principalData'.
|
Ultimately, I removed the intermediate inheritance and are referencing Report.CorrelationRecord(V0/V1) directly. |
JagdishKhunti
deleted the
LAB-981_describe-new-v1-ArchitectureReport-endpoints-in-OpenApi
branch
Summary
Adds and expands ArchitectureReport V1 schemas, examples, and endpoints; clarifies permissions/scope notes.
Renames LicenseReport schemas to LicenseReportV0 and updates all internal references for explicit versioning.
Refactors principal data models (introduces CommonPrincipalAssignment, DevicePrincipalAssignment, UserPrincipalAssignment) to remove duplication and support nullable/enhanced identity fields.
Converts single example fields into examples arrays and adds richer example objects for assigned licenses, users, and devices.
Standardizes API error handling by adding 500 Internal Server Error responses across many endpoints and harmonizing response codes (some 201 → 200).
Adjusts required fields for the correlation record schema (final change reduces required to only auditTenantAccount) and updates examples accordingly.
Misc: improved operationId naming, titles, descriptions, and example coverage for better documentation and client generation.
Key changes (high level)
Schemas
Introduce ArchitectureReportV1 and related correlation record changes.
Rename LicenseReport → LicenseReportV0 and update references.
Add CommonPrincipalAssignment and use allOf to extend for device/user variants.
Extract and standardize repeated patterns (assigned license items, count maps, additional service unions) where possible.
Examples
Replace many inline example fields with examples arrays; add comprehensive example objects for architecture and license reports.
Ensure examples match the tightened schema requirements (correlation record required fields reduced).
Paths / Responses
Add 500 responses to multiple endpoints; add/adjust 401/403 where appropriate.
Clarify POST/GET /Api/V1/ArchitectureReport descriptions with permission and tenant access notes.
Standardize response codes and add summaries/descriptions to improve generated docs.
Internal housekeeping
Several merges and refactors from feature branches; multiple authors (Jesse H, JagdishKhunti).
Numerous small fixes to examples and schema consistency.