Ask HN: Non-Breaking API deprecation in OpenAPI spec – what do you think?

1 point

4 years ago

Sometimes APIs need to be retired, for example when they are superseded by a new version. OpenAPI specification supports a "deprecated" flag which can be used to mark operations and other object types as deprecated, but it lacks the ability to manage a 2-phased API retirement process: 1. Deprecate an API and, optionally, announce a "sunset" date 2. Delete the API at the sunset date or later

People seem to want such a process in order to prevent breaking-changes.

I wrote a diff tool for OpenAPI spec which supports detection of breaking-changes and I recently extended it to support this process and a bit more.

Now I'm looking for feedback.

Proposed Solution (currently in Beta): https://github.com/Tufin/oasdiff#non-breaking-removal-of-deprecated-resources

Related requests: 1. https://github.com/Tufin/oasdiff/issues/116 2. https://github.com/OAI/OpenAPI-Specification/discussions/2770

Your feedback is much appreciated!