Jak sleduju změny v API - praktický návod

API je smlouva mezi backendem a frontendem. Když se změní a nikomu to neřekneš, máš problém. Proto sledování API změn beru vážně.

Jaké změny řešíme

Breaking changes (rozbijí klienty):

• Odebrání endpointu
• Změna typu parametru
• Změna struktury response

Non-breaking změny (v pohodě):

• Nový endpoint
• Nový optional parametr
• Nové pole v response

Deprecations - "tohle půjde pryč, máš čas se připravit"

Bug fixy - opravy, ale opatrně, někdy to změní chování

OpenAPI spec diffing

Tohle je základ. OpenAPI spec je strojově čitelná definice API. Diff mezi verzemi ukáže přesně co se změnilo.

Nástroje co používám:

• openapi-diff - automaticky porovná specs
• oasdiff - identifikuje breaking changes
• Výstup jde rovnou do CI/CD

Semantic versioning

Klasika:

• Major (X.0.0) - breaking changes
• Minor (0.X.0) - nové features, zpětně kompatibilní
• Patch (0.0.X) - bug fixy

Verzi dávám do URL (/api/v2/users) nebo do headerů. Každý ví co používá.

Automatický changelog

Máme tohle:

1. Git commity s conventional commit messages
2. CI extrahuje API změny z OpenAPI spec diffu
3. Generuje se human-readable changelog
4. Publikuje se na developer portal

Není to dokonalé, ale lepší než psát changelog ručně.

Breaking changes v CI

Tohle je důležité:

1. PR pipeline automaticky porovná OpenAPI specs
2. Když najde breaking change, build failne
3. Developer musí buď změnit přístup, nebo bumplout major verzi
4. Notifikujeme API consumery předem

Zachránilo nás to už mockrát.

Deprecation - jak na to správně

1. Označ v OpenAPI spec - deprecated: true
2. Vrať warning v response - Sunset header s datem
3. Napiš migration guide - co použít místo toho
4. Monitoruj usage - kdo to ještě používá?
5. Komunikuj - hlavně s heavy users
6. Odstraň jen v major verzi

Komunikace s vývojáři

Co děláme:

• Changelog na developer portálu
• Email notifikace pro major změny
• Migration guides s příklady kódu
• Support pro problematické migrace
• Compatibility matrix - co s čím funguje

---

Sledování API změn je práce navíc, ale vyplatí se. Lepší než v pátek v noci řešit proč klientům spadla integrace.

Potřebuješ porovnat OpenAPI specs? Exportuj jako JSON a hoď do JSON Diff.