DEV Community

Cover image for What counts as a breaking change in an OpenAPI spec
Georgi Kalchev
Georgi Kalchev

Posted on Originally published at aiskills402.com

What counts as a breaking change in an OpenAPI spec

A breaking change depends on which way the data flows. Requests may loosen and responses may tighten; the reverse breaks clients. A field guide with examples.

A breaking change is any edit to an API description after which a client written against the old description stops working against the new one. Every other edit is safe. That sounds obvious, but in practice people sort changes by how big they look: a removed endpoint feels dangerous, a new enum value feels harmless. The better question is which way the data travels. A client sends requests and reads responses, so the same edit can be safe on one side and harmful on the other. Below you will find the direction rule, the edits that are most often misjudged, and a short routine for reviewing pull requests.

Read the full report on AISkills402: https://aiskills402.com/blog/openapi-breaking-changes?utm_source=devto&utm_medium=social

Top comments (0)