It currently supports version 2, a version 3 is on the agenda - if the tool is found useful.

The value proposal is to make a tool that helps service developer to keep on evolving their services in the highest possible pace. If a service is used by many different clients it is important that they can continue to operate and create value for the users (and that creates value at the service as well). If the service API cannot be evolved because one or more clients are having trouble working with new versions either every version is a completely new service or the existing service has some built in mechanisms that helps the client developers to cope with change and offers then a easy and swift fall-back. This is the goal of this tool.

The Open API diff tool compares 2 APIs (an existing API and the future API). The two APIs can be analyzed according to a certain depth a certain maturity and something called versions (see below).

In other words the tool is aimed at comparing an existing API, with a future API and deliver results on breaking changes, potentially breaking changes etc. that could make clients (service users) unhappy.

The tool comprises currently 3 different reports:

• HTML report
• MarkDown report
• A Console Report (including text based report)

The Reports will contain information based on the depth, maturity and version settings. The most elaborate of the reports will list the following sections:

• added,
• removed and
• changed resources

• breaking stuff
• potentially breaking stuff

The report will show breaking and potentially breaking observations that occurs as a result of a change from the existing API to the coming API, but it will also include suggested improvements to the existing in order to be able to go from the existing towards a new future version of the service with the least possible pain for the client. Basically these suggestions could be considered as candidates for a gradual implementation in the existing API and be a part of the existing API before moving to the future API. The reasoning behind that is that clients needs to incorporate some of e.g. the response codes into their programming model in order to react easily to API evolution.

• breaking stuff

• potentially breaking stuff

• changes

• improvements to existing API

• changes to content-types

• changes to parameters

• changes to properties

• changes to responses

The report will show breaking and potentially breaking observations that occurs as a result of a change from the existing API to the coming API and includes suggested improvements to the existing in order to be able to go from the existing towards a new future version of the service with the least possible pain for the client. Basically these suggestions could be considered as candidates for a gradual implementation in the existing API and be a part of the existing API before moving to the future API. The reasoning behind that is that clients needs to incorporate some of e.g. the response codes into their programming model in order to react easily to API evolution.

The tool can be used with different settings, the level of depth in the analysis can be set and so can the maturity and versions.

• all everything that can be checked upon is included in the report, this together with maturity full will give the most elaborate report.
• breaking this will only report breaking changes
• potentially breaking this will report breaking and potentially breaking changes
• laissez-faire this will report changes at the endpoint level

###The maturity can be set into:

• full this is the most elaborated check
• low this is the most relaxed check and usually used together with laissez-faire depth

Using the full maturity gives feedback at Richardson maturity model highest level for opinionated REST services using HAL (see section on the opinionated parts below)

The Open API Diff project is maven based and thus it can be build by using:

mvn verify  

This will compile and run tests (unit-, integration- and verification-tests) More information on the thoughts on the structure etc. in the project

Use with different levels of how to work with the opinionated stuff such as the diff-level, maturity level, etc. can be found in the usage information

The reports are made in a first rudimentary form and it is hoped that the use of the tool will lead to reports that are taylormade to the needs that hopefully is there for service developers to be able to determine in an easy and predictable way whether the coming API is backward compliant or not and whether some clients may see the new version breaking stuff in the application using the service and thus providing its users with a bad experience.

Currently 3 reports are supported (HTML, MarkDown, TXT).

The findings will be shown and exemplified by the use of the HTML based report in order to show something visual along with an explanation of why this finding exist and why it is a part of the report.

The current edition is merely a tool in its early stages, if this is found useful, it could evolve into a more elaborate tool. Currently this seems to require some consensus on the opinionated parts in order to get the most value from the comparison of APIs. Support for configuration of a response, header, etc. profile, that suits individual needs. Support for API capabilities as shown in the api capabilities is one of the things under consideration, but first a stable version of the current version needs to be verified by others in order to see the potential for the tool.

The inspiration was found in the existing tools for swagger-diff, and the wish to take responses, headers and content-types into the tooling. The implementation took its starting point in the deepoove project on swagger-diff. A big thanks goes to the swagger-diff people.

The samples from the swagger-diff project has been kept in the project to let people having experiences with the swagger-diff project have an easy way to get started with this if they want to use a more opinionated tool. The diffs done in swagger-diff can be done in this tool tool. Being the opinionated tool it is these chacks are not the default ones.