API Changes Compatibility Suite

Summary

During comparison of API specifications, APIHUB (qubership-apihub-api-diff) classifies each change by one of the following severity type:

• Breaking change is a change that breaks backward compatibility with the previous version of API. For example, deleting an operation, adding a required parameter or changing type of a parameter are breaking changes.
• Deprecating change is a change that annotates an operation, parameter or schema as deprecated. Removing a "deprecated" annotation is also considered a deprecating change.
• Non-breaking change is change that does not break backward compatibility with the previous version of API. For example, adding new operation or optional parameter is non-breaking change.
• Annotation change is a change to enrich the API documentation with information that does not affect the functionality of the API. For example, adding/changing/deleting descriptions or examples is annotation change. Unclassified change is a change that cannot be classified as any of the other types.

Current page contains compatibility suite for API specification changes for OpenAPI 3.0 and GraphQL (release October 2021).

OpenAPI

Genereal Operation Parameters

1. add new endpoint

Add enpoint with one method

path to the change	change id	link	severity
paths.[<path>]	add-new-path		non-breaking

Example:

Before:

openapi: 3.0
...
paths:
    /pets:
        post:
            ...

After:

openapi: 3.0
...
paths:
    /pets:
        post:
            ...
    /petstore:
        get:
            ...

---

2. remove endpoint

Remove endpoint with one method

path to the change	change id	link	severity
paths.[<path>]	remove-path		breaking

Example:

Before:

openapi: 3.0
...
paths:
    /pets:
        post:
            ...
    /petstore:
        get:
            ...

After:

openapi: 3.0
...
paths:
    /pets:
        post:
            ...

---

3. add new method

path to the change	change id	link	severity
paths.[*].[<method>]	add-new-method		non-breaking

Example:

Before:

openapi: 3.0
...
paths:
  /pets:
    post:
      ...

After:

openapi: 3.0
...
paths:
  /pets:
    post:
      ...
    get:
      ..

---

4. remove method

Remove non-deprecated method

path to the change	change id	link	severity
paths.[*].[<method>]	remove-method		breaking

Example:

Before:

openapi: 3.0
...
paths:
  /pets:
    post:
      ...
    get:
      ...

After:

openapi: 3.0
...
paths:
  /pets:
    post:
      ...

---

5. add tag

Add tag to the operation

path to the change	change id	link	severity
paths.[*].[*].tags.<value>	add-tag		annotation

Example:

Before:

openapi: 3.0
tags:
  - name: tag1
paths:
  /pets:
    post:
      summary: Returns a list of pets.
      responses:
        "200":
          description: Ok

After:

openapi: 3.0
tags:
 - name: tag1
...
paths:
  /pets:
    post:
      tags:
        - tag1
      summary: Returns a list of pets.
      responses:
        "200":
          description: Ok