Matching of REST operations during comparison

[iugaidiana]

Package version v1 has operation, for example - GET /api/v2/packages/{packageId}. In v2, user changes name of path parameter from "packageId" to "id", i.e. operation looks like GET /api/v2/packages/{id}. Since path parameters (packageId/id) are variables, then change of path parameter name does not break backward compatibility.

During comparison of v1 vs v2, the system shall match GET /api/v2/packages/{packageId} and GET /api/v2/packages/{id}; compare them and show changes.

The problem is that currently, when we compare v1 vs v2, the system does not match GET /api/v2/packages/{packageId} with GET /api/v2/packages/{id}, but shows that GET /api/v2/packages/{packageId} was deleted and GET /api/v2/packages/{id} was added. The reason is that the system matches operations by operation id. Operation id is generated by the following logic: path elements of operation's path + method; i.e.:

• GET /api/v2/packages/{packageId} has operation id = api-v2-packages-packageId-get
• GET /api/v2/packages/{id} operation id = api-v2-packages-Id-get

There are two options to fix this problem:

Option 1: change logic of generation of rest operation id. So the new logic, instead of taking the path parameter name as is, will replace it with some fixed value. For example, instead of path parameter name, use asterisk character. In this case, the operations from the example above will have the same ids:

• GET /api/v2/packages/{packageId} will have operation id = api-v2-packages-*-get
• GET /api/v2/packages/{id} will have operation id = api-v2-packages-*-get

Cons of this option is that all links to old operations will be broken.

Option 2: Change the logic of matching operations during comparison. Potential disadvantages of this approach are that applying matching logic at runtime may increase the time of comparison.

In scope of this issue, it is needed to analyze and make assessment of options.