Verzování API

Backend API Sencai je verzováno pod jmenným prostorem /api/v1/. Tato stránka vysvětluje, co se považuje za breaking change, jak dlouho zůstávají deprecated cesty funkční, a jak migrovat existující integrace.

Jmenné prostory

Cesta	Stav	Poznámka
`/api/v1/*`	Aktuální, doporučené	Kanonická verzovaná cesta. Chování identické s `/api/*` — jde o transparentní alias před stejnými routami/kontrolery, ne o samostatnou implementaci.
`/api/*`	Deprecated, stále podporované	Zachováno jako zpětně kompatibilní alias, aby se nerozbily existující integrace. Každá odpověď nese hlavičku `Warning: 299`. Není redirectováno (žádné `301`) ani odstraněno — jde o aditivní změnu.

Každá odpověď z obou cest nese:

X-API-Version: 1
Deprecation: false

Deprecation: false se vztahuje k aktuální verzi API (v1) samotné — v1 není deprecated. Deprecated je pouze neverzovaná cesta /api/* ve prospěch /api/v1/*, proto je hlavička Warning scoped jen na tento alias.

Příklad odpovědi z deprecated aliasu:

HTTP/1.1 200 OK
X-API-Version: 1
Deprecation: false
Warning: 299 - "Deprecated path /api, use /api/v1"
Sunset: Wed, 01 Oct 2026 00:00:00 GMT

API Manager (`api-manager`, port 3200)

Stejný vzor platí i pro službu API Manager, která vydává Strapi API tokeny ostatním microservices:

Cesta	Stav
`POST /v1/token/:service`, `/v1/admin/*`	Aktuální, doporučené
`/api/token/:service`, `/api/admin/*`	Deprecated alias — stále funguje, nese hlavičku `Sunset`

Chování deprecation hlaviček není identické mezi oběma službami. Strapi middleware pro legacy alias posílá jen X-API-Version / Deprecation / Warning / Sunset — neposílá hlavičku Link. Versioning middleware API Manageru navíc, pokud se uplatní deprecated version policy, posílá hlavičku Link: <migration_guide_url>; rel="deprecation" odkazující na migrační průvodce, převzatou z odpovídajícího záznamu api-version-policy. Pokud stavíte tooling, který generický parsuje deprecation hlavičky napříč oběma službami, nepředpokládejte přítomnost hlavičky Link u každé deprecated odpovědi — ověřte to per-service.

Breaking vs non-breaking změny

Non-breaking (lze nasadit bez bumpu verze):

Přidání nového volitelného pole do response body
Přidání nového endpointu
Přidání nového volitelného query parametru
Uvolnění validačního pravidla (přijetí dříve odmítaného vstupu)
Přidání nových enum hodnot u pole dokumentovaného jako „otevřené” / rozšiřitelné

Breaking (vyžaduje novou verzi, např. /api/v2/):

Odstranění nebo přejmenování pole v response
Odstranění nebo přejmenování endpointu
Změna typu pole (např. string → number)
Změna dříve volitelného pole požadavku na povinné
Změna významu/sémantiky existujícího pole
Změna autentizačních/autorizačních požadavků na existujícím endpointu
Změna výchozího chování stránkování/řazení

Pokud je změna breaking, nasazuje se pod novým verzním prefixem (/api/v2/), zatímco /api/v1/ pokračuje v obsluze starého chování až do vlastního sunset data — stejná politika popsaná zde platí pro každou budoucí verzi.

Versioning SLA (deprecation timeline)

Neverzovaný alias /api/* je deprecated, ale zatím nemá oznámené pevné datum odstranění — sleduje se přes response hlavičku Sunset, která se počítá z proměnné prostředí SUNSET_DATE (ISO datum, např. 2026-10-01) jak na Strapi backendu, tak na API Manageru.
Pokud SUNSET_DATE není nastaveno, výchozí hodnota je 90 dní od startu procesu — tedy minimální garantovaná lhůta upozornění před případným sunsetem aliasu je 90 dní.
Dosažení data Sunset automaticky neznamená, že alias přestane fungovat — sunset data jsou provozní cíle komunikované předem přes tuto hlavičku, release notes a přímé e-mailové oznámení.
E-mailové oznámení se odešle automaticky ve chvíli, kdy admin nastaví nebo změní datum deprecated_at/sunset_at u politiky (nejen jednou po dosažení daného data) — dostane ho každý aktivní Owner/Admin napříč všemi organizacemi na platformě, včetně účinného data a odkazu na migračního průvodce, pokud je nakonfigurovaný. Jde o best-effort vedlejší kanál nad rámec hlaviček Sunset/Warning, ne o jejich náhradu — selhání odeslání e-mailu nikdy neblokuje samotnou změnu politiky.
Organizace s nakonfigurovaným customer webhookem na api.version.deprecated nebo api.version.sunset dostanou stejnou změnu i tímto kanálem.
Skutečné odstranění je samostatně oznámená, záměrná změna.

Aktuální hodnotu Sunset lze kdykoliv ověřit:

curl -sI https://api.sencai.space/api/organisations | grep -i sunset

Jak migrovat

Migrace z /api/ na /api/v1/ nevyžaduje žádné funkční změny — pouze aktualizaci base URL:

Najděte všechna místa, kde vaše integrace sestavuje request URL proti Strapi backendu (https://api.sencai.space/api/... nebo lokální dev ekvivalent).
Nahraďte prefix /api/ za /api/v1/ — tvar requestu/response, autentizace (Authorization: Bearer <JWT>) i status kódy zůstávají nezměněné.
Spusťte znovu testovací sadu / smoke testy proti /api/v1/* pro ověření parity.
Po migraci můžete bezpečně ignorovat hlavičky Warning/Sunset, protože vaše integrace už nevolá deprecated alias.

Příklad:

GET https://api.sencai.space/api/organisations
GET https://api.sencai.space/api/v1/organisations

Pro služby využívající API Manager k získání Strapi tokenů:

GET http://api-manager:3200/api/token/git-connector
GET http://api-manager:3200/v1/token/git-connector

Žádná další změna není potřeba — jmenný prostor /api/v1/* je transparentní alias, ne přepis podkladové implementace, takže chování je identické s tím, co /api/* vrací už dnes.

Implementační poznámka

Toto verzovací schéma bylo implementováno jako F3.API.01:

sencai.space: src/middlewares/api-version.ts (+ src/middlewares/__tests__/api-version.test.ts)
api-manager: src/middleware/api-versioning.ts

Verzování API

Verzování API

Jmenné prostory

API Manager (api-manager, port 3200)

Breaking vs non-breaking změny

Versioning SLA (deprecation timeline)

Jak migrovat

Implementační poznámka

API Manager (`api-manager`, port 3200)