Loading…
Loading…
Compares two versions of a service to produce a detailed report of added, removed, and modified operations, including field-level differences.
The Service Version Comparison component provides a mechanism to analyze the differences between two distinct versions of a service. It is designed for API publishers who need to understand the evolution of a service, track changes to its operations, and review the history of modifications.
The component takes the unique identifiers for a service and two of its versions as input. It produces a structured report detailing all added, removed, and modified operations. The comparison includes specific field-level changes for each modified operation, a summary of total changes, and a list of recent audit events related to the compared entities.
The comparison process is initiated by calling the compare method with a service ID and two version IDs (a "left" and "right" version for comparison). The component then performs the following sequence of operations:
s2r_service_version table. This includes version number, status, and creation details.s2r_operation table. Operations are indexed by their unique operation_key.operation_key values from both versions. It then iterates through this set to compare the left and right operations for each key.
added if it exists in the right version but not the left.removed if it exists in the left version but not the right.changed if it exists in both versions but one or more of its tracked fields have different values.unchanged.s2r_audit_event table for the most recent audit events related to these entities, up to a limit of 120.The following diagram illustrates the data flow for a version comparison.
flowchart TD
A[compare(serviceId, leftVersionId, rightVersionId)] --> B{Load Metadata & Operations};
B --> C[Load Left Version & Operations];
B --> D[Load Right Version & Operations];
C & D --> E{Compare Operations by Key};
E --> F[Identify Added, Removed, Changed];
F --> G{Aggregate Results};
G --> H[Load Related Audit Events];
H --> I[Return Comparison Report];The core functionality is exposed through the VersionCompareService.compare method.
compareThis method compares two service versions and returns a detailed report of the differences.
| Name | Type | Required | Description |
|---|---|---|---|
serviceId | UUID | Yes | The unique identifier of the service containing the versions to compare. |
leftVersionId | UUID | Yes | The unique identifier of the base version for the comparison. |
rightVersionId | UUID | Yes | The unique identifier of the version to compare against the base version. |
The method returns a map containing a structured comparison report. The source does not provide a concrete example payload. The structure of the response is detailed below.
| Field | Type | Description |
|---|---|---|
serviceId | UUID | The ID of the service whose versions were compared. |
leftVersion | Object | Metadata for the base version. See Version Metadata. |
rightVersion | Object | Metadata for the compared version. See Version Metadata. |
summary | Object | A summary of changes. See Summary Object. |
operationChanges | Array of Objects | A list of all detected operation changes. See Operation Change Object. |
auditEvents | Array of Objects | A list of recent audit events related to the compared versions and their operations. See Audit Event Object. |
This object contains metadata for a single service version.
| Field | Type | Description |
|---|---|---|
id | UUID | The version's unique identifier. |
versionNo | Integer | The sequential version number. |
status | String | The lifecycle status of the version (e.g., "DRAFT"). |
active | Boolean | true if this is the currently active version of the service. |
createdAt | OffsetDateTime | The timestamp when the version was created. |
createdBy | String | The identity of the user who created the version. |
This object provides a high-level count of the differences found.
| Field | Type | Description |
|---|---|---|
added | Integer | The number of operations added in the right version. |
removed | Integer | The number of operations removed from the right version. |
changed | Integer | The number of operations that were modified between versions. |
unchanged | Integer | The number of operations that were identical in both versions. |
This object describes a single change to an operation.
| Field | Type | Description |
|---|---|---|
operationKey | String | The unique key identifying the operation within the service. |
changeType | String | The type of change: added, removed, or changed. |
changedFields | Array of Strings | For changed operations, lists the names of modified fields. For added or removed operations, this field contains ["operation"]. |
summary | String | A human-readable summary of the change (e.g., a comma-separated list of changed fields). |
leftOperationId | UUID | The ID of the operation in the left version. null if the operation was added. |
rightOperationId | UUID | The ID of the operation in the right version. null if the operation was removed. |
leftRoute | String | The REST route (METHOD /path) in the left version. null if the operation was added. |
rightRoute | String | The REST route (METHOD /path) in the right version. null if the operation was removed. |
This object represents a single audit event related to the compared entities.
NOTE
The beforeState and afterState fields have any sensitive or secret settings automatically redacted. The list of events is limited to the 120 most recent records associated with the compared entities.
| Field | Type | Description |
|---|---|---|
id | UUID | The unique ID of the audit event. |
occurredAt | Timestamp | The timestamp when the event occurred. |
actorEmail | String | The email of the user or principal that performed the action. |
actorRole | String | The role of the actor. |
actionType | String | The type of action performed (e.g., "CREATE", "UPDATE"). |
entityType | String | The type of entity that was affected (e.g., "ServiceVersion"). |
entityId | UUID | The unique ID of the affected entity. |
beforeState | String (JSON) | The state of the entity before the action. Secret values are redacted. |
afterState | String (JSON) | The state of the entity after the action. Secret values are redacted. |
correlationId | String | An ID to correlate related events. |
result | String | The outcome of the action (e.g., "SUCCESS", "FAILURE"). |
message | String | A descriptive message about the event. |
When an operation exists in both service versions, it is marked as changed if any of the following fields differ.
| Field Name | Description |
|---|---|
soapOperationName | The name of the SOAP operation. |
soapAction | The SOAPAction HTTP header value. |
restMethod | The HTTP method for the REST endpoint. |
restPath | The path for the REST endpoint. |
timeoutMs | The operation-specific timeout in milliseconds. |
retryCount | The number of retries for the operation. |
debugEnabled | A flag indicating if debugging is enabled. |
requestSchema | The JSON schema for the request payload. |
responseSchema | The JSON schema for the response payload. |
faultSchema | The JSON schema for the fault or error payload. |
serviceId and versionId (leftVersionId or rightVersionId) do not correspond to an existing service version record.compare operation fails and throws an IllegalArgumentException.