data-api-differ

Tool: data-api-differ

This tool takes two sets of API Definitions and diffs them in several ways:

1. Detects any Breaking Changes between the two sets of API Definitions.
2. Detects any Breaking and Non-Breaking Changes between the two sets of API Definitions.
3. Detects any new Resource ID Segments containing any new Static Identifiers which need to be reviewed (e.g. the fixed value associated with a Resource Provider or Static Resource ID Segment).

These are available as three sub-commands and are described below.

Example Usage

$ ./data-api-differ [source-data-type]
2023-12-07T12:16:15.106+0100 [INFO]  Data API Differ launched..
Usage: data-api-differ [--version] [--help] <command> [<args>]

Where Source Data Type is one of: [microsoft-graph resource-manager]

Available commands are:
    detect-breaking-changes        Retrieves two sets of API Definitions from the Data API and determines if there are any breaking changes
    detect-changes                 Detects any changes between the existing and updated set of API Definitions
    output-resource-id-segments    Determines the new Resource IDs and then outputs a unique, sorted list of Static Identifiers found in the Resource ID Segments for review.

Specific examples for each command can be found below.

Supported Arguments

All the subcommands support the same set of arguments:

• (Required) --initial-path specifies the path to the directory containing the initial/existing set of API Definitions.
• (Required) --updated-path specifies the path to the directory containing the updated set of API Definitions.
• (Optional) --data-api-binary-path specifies the path to the Data API (V2) binary. If unspecified, it's assumed this exists on the PATH (e.g. sourced from $GOPATH/bin).
• (Optional) --output-file-path specifies the path where the result should be output to. If unspecified, this is output to the terminal.

Logging can be configured using the LOG_LEVEL environment variable (e.g. LOG_LEVEL=trace).

Example Usage: Detecting Breaking Changes

This command detects both Breaking Changes that exist between the two sets of API Definitions.

Command:

$ go build . && ./data-api-differ resource-manager detect-breaking-changes --initial-path=/path/to/initial-api-definitions --updated-path=/path/to/updated-api-definitions

This command supports each of the arguments defined under Supported Arguments above.

Example output:

2023-12-07T12:32:07.937+0100 [INFO]  Data API Differ launched..
2023-12-07T12:32:07.937+0100 [INFO]  Running `detect-breaking-changes` command..
2023-12-07T12:32:07.941+0100 [INFO]  Data API Binary located at "data-api"
2023-12-07T12:32:07.941+0100 [INFO]  Initial API Definitions located at: "/path/to/initial-api-definitions"
2023-12-07T12:32:07.941+0100 [INFO]  Updated API Definitions located at: "/path/to/updated-api-definitions"
2023-12-07T12:32:07.941+0100 [INFO]  Output will be rendered to the console since no output file was specified
2023-12-07T12:32:07.941+0100 [INFO]  Launching Data API..
2023-12-07T12:32:08.952+0100 [INFO]  Retrieving Services..
2023-12-07T12:32:09.086+0100 [INFO]  Launching Data API..
2023-12-07T12:32:10.096+0100 [INFO]  Retrieving Services..
2023-12-07T12:32:10.098+0100 [INFO]  Identifying a unique list of Service Names..
2023-12-07T12:32:10.098+0100 [INFO]  Detecting changes in Service "AADB2C"..
2023-12-07T12:32:10.098+0100 [INFO]  Detecting changes in Service "Compute"..
2023/12/07 12:32:10## Breaking Changes

🛑 **2 Breaking Changes** were detected.

---

Summary of changes:

* ❌ **Removed Service:** `AADB2C`.
* ❌ **Removed Service:** `Compute`.

Example of the Markdown Comment (rendered as Markdown):

## Breaking Changes

🛑 **2 Breaking Changes** were detected.

---

Summary of changes:

* ❌ **Removed Service:** `AADB2C`.
* ❌ **Removed Service:** `Compute`.

Example Usage: Detecting Changes

This command detects both Breaking and Non-Breaking Changes that exist between the two sets of API Definitions.

Command:

$ go build . && ./data-api-differ resource-manager detect-changes --initial-path=/path/to/initial-api-definitions --updated-path=/path/to/updated-api-definitions

This command supports each of the arguments defined under Supported Arguments above.

Example output:

2023-12-07T12:31:01.837+0100 [INFO]  Data API Differ launched..
2023-12-07T12:31:01.837+0100 [INFO]  Running `detect-changes` command..
2023-12-07T12:31:01.837+0100 [INFO]  Data API Binary located at "data-api"
2023-12-07T12:31:01.837+0100 [INFO]  Initial API Definitions located at: "/path/to/initial-api-definitions"
2023-12-07T12:31:01.837+0100 [INFO]  Updated API Definitions located at: "/path/to/updated-api-definitions"
2023-12-07T12:31:01.837+0100 [INFO]  Output will be rendered to the console since no output file was specified
2023-12-07T12:31:01.837+0100 [INFO]  Launching Data API..
2023-12-07T12:31:02.847+0100 [INFO]  Retrieving Services..
2023-12-07T12:31:02.983+0100 [INFO]  Launching Data API..
2023-12-07T12:31:03.989+0100 [INFO]  Retrieving Services..
2023-12-07T12:31:04.117+0100 [INFO]  Identifying a unique list of Service Names..
2023-12-07T12:31:04.117+0100 [INFO]  Detecting changes in Service "AADB2C"..
2023-12-07T12:31:04.117+0100 [INFO]  Detecting changes in Service "Compute"..
2023/12/07 12:31:04 ## Summary of Change## Summary of Changes

* 👍 No Breaking Changes were detected.
* 👀 1 Non-Breaking Changes were detected.

---


## Non-Breaking Changes

**1 Non-Breaking Changes** were detected:

* ✅ **New Constant:** `PerformanceTier` (Type `string`) in `Compute@2021-07-01/DedicatedHost`. Possible Values: `Fast: Fast`, `None: None`, `VeryFast: VaVaVoom`.

Example of the Markdown Comment (rendered as Markdown):

## Summary of Changes

* 👍 No Breaking Changes were detected.
* 👀 1 Non-Breaking Changes were detected.

---


## Non-Breaking Changes

**1 Non-Breaking Changes** were detected:

* ✅ **New Constant:** `PerformanceTier` (Type `string`) in `Compute@2021-07-01/DedicatedHost`. Possible Values: `Fast: Fast`, `None: None`, `VeryFast: VaVaVoom`.

Example Usage: Outputting the list of new Static Identifiers found within any new Resource IDs

This command detects any new Resource IDs or Resource ID Segments which are new/have been updated between the two sets of API Definitions, identifies any Static Identifiers (e.g. the Fixed Value for a Resource Provider or Static Resource ID Segment) and then outputs a unique, sorted list of these for review.

Command:

$ go build . && ./data-api-differ resource-manager output-resource-id-segments --initial-path=/path/to/initial-api-definitions --updated-path=/path/to/updated-api-definitions

This command supports each of the arguments defined under Supported Arguments above.

Example output:

2023-12-07T12:29:36.823+0100 [INFO]  Data API Differ launched..
2023-12-07T12:29:36.823+0100 [INFO]  Running `output-resource-id-segments` command..
2023-12-07T12:29:36.823+0100 [INFO]  Data API Binary located at "data-api"
2023-12-07T12:29:36.823+0100 [INFO]  Initial API Definitions located at: "/path/to/initial-api-definitions"
2023-12-07T12:29:36.823+0100 [INFO]  Updated API Definitions located at: "/path/to/updated-api-definitions"
2023-12-07T12:29:36.823+0100 [INFO]  Output will be rendered to the console since no output file was specified
2023-12-07T12:29:36.823+0100 [INFO]  Launching Data API..
2023-12-07T12:29:37.845+0100 [INFO]  Retrieving Services..
2023-12-07T12:29:38.007+0100 [INFO]  Launching Data API..
2023-12-07T12:29:39.021+0100 [INFO]  Retrieving Services..
2023-12-07T12:29:39.176+0100 [INFO]  Identifying a unique list of Service Names..
2023-12-07T12:29:39.176+0100 [INFO]  Detecting changes in Service "AADB2C"..
2023-12-07T12:29:39.177+0100 [INFO]  Detecting changes in Service "Compute"..
2023/12/07 12:29:39 ## New Resource ID Segments containing Static Identifiers

The following new Static Identifiers were detected from the set of changes (new/updated Resource IDs).

> ⚠️ Note: Resource ID segments should **always** be `camelCased` and not `TitleCased`, `lowercased` or `kebab-cased`.

Please review the following list of Static Identifiers:

---

* `Microsoft.Compute`
* `favouriteHostGroups`
* `hostGroups`
* `providers`
* `resourceGroups`
* `subscriptions`

---

> ⚠️ Note: Resource ID segments should **always** be `camelCased` and not `TitleCased`, `lowercased` or `kebab-cased`.

Example of the Markdown Comment (rendered as Markdown):

## New Resource ID Segments containing Static Identifiers

The following new Static Identifiers were detected from the set of changes (new/updated Resource IDs).

> ⚠️ Note: Resource ID segments should **always** be `camelCased` and not `TitleCased`, `lowercased` or `kebab-cased`.

Please review the following list of Static Identifiers:

---

* `Microsoft.Compute`
* `favouriteHostGroups`
* `hostGroups`
* `providers`
* `resourceGroups`
* `subscriptions`

---

> ⚠️ Note: Resource ID segments should **always** be `camelCased` and not `TitleCased`, `lowercased` or `kebab-cased`.