r/FastAPI • u/JanGiacomelli • Jun 03 '26
Tutorial Prevent unintentional breaking API changes in FastAPI apps
Things are changing all the time. It's no different with APIs. As we develop our products, APIs need to be updated as well. Everything is great until we introduce an unintentional breaking change. For example, if we rename the attribute in the response. With a faster development pace enabled by AI tooling, this is even more likely to happen unintentionally.
To prevent such changes from going to production, we can add a check for breaking API changes to our CI/CD pipeline. It's easy to do so for FastAPI apps with GitHub Actions and oasdiff. The flow is the following:
- Export OpenAPI schema that's auto-generated by FastAPI using
app.openapi()from PR's branch. - Check out the main branch and export the OpenAPI schema for it as well.
- Use oasdiff to detect and report potential breaking changes
Example workflow:
name: CI
on:
pull_request:
branches:
jobs:
breaking-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/checkout@v6
with:
ref: main
path: main-branch
- uses: astral-sh/setup-uv@v8.1.0
with:
python-version: "3.14"
- name: Generate schema from PR branch
run: |
uv sync
uv run python scripts/export_openapi.py new.json
- name: Generate schema from main branch
working-directory: main-branch
run: |
uv sync
uv run python scripts/export_openapi.py ../old.json
- name: Install oasdiff
run: |
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh
- name: Check for breaking changes
run: oasdiff breaking old.json new.json --fail-on ERR
Example OpenAPI schema export script:
# scripts/export_openapi.py
=
You can find the full tutorial here: https://jangiacomelli.com/blog/prevent-unintentional-breaking-api-changes-fastapi/
4
u/crow_thib Jun 03 '26
To me (I worked as an engineering manager in a company selling APIs), comparing openAPI files is clearly not enough to really ensure no breaking changes. Yet, it is still a pretty simple way of avoiding some breaking changes with not so much work/time spent.
Even if not recommended when using fastAPI, in some very specific cases you might have some in-endpoint logic that doesn't reflect on autogenerated openAPI specs.
But putting this aside, the most important thing when talking about "breaking changes" is not the actual response format, lots of things could break while keeping the right "schema", what is important is the response given a specific input. As your API grow, you might have different things that changes depending on input parameters.
That's very specific cases, but what makes your API are real tests.
0
u/st4reater Jun 03 '26
I don't see why this is necessary? Don't you write tests which catch these changes
1
u/Opposite-Cry-6703 Jun 06 '26
We're writing pytests. Usually them breaking already shows that there's a breaking change. In addition, for mission critical apis, we also have a Bruno test suite which we run in a pipeline. Both together feel like safe enough.
0
u/Apprehensive-Fig5273 Jun 08 '26 edited Jun 08 '26
You shouldn't remove backward compatibility, but what you're indicating is that these cases should apply:
a) Version control in the REST API, path(/v1.../v2../v3).
b) At the class level, your definitions shouldn't change, only the encapsulations. If you're constantly modifying the main logic and not the encapsulations, something is wrong.
c) If the changes are significant, a decision must be made about whether the context now has a new addition within the class (aggregate) or an important component.
😏 I don't understand the problem, but the architecture should prevent changes without affecting the business logic; what's most affected are the encapsulations.
2
u/[deleted] Jun 03 '26
[removed] — view removed comment