---
title: "Verzování API a zpětná kompatibilita"
description: "Změna, která vypadá neškodně — přejmenování jednoho pole — dokáže odstavit integraci u zákazníka, o kterém jste nevěděli, že existuje."
canonical: "https://interfase.sk/cz/novinky/verzovani-api-a-zpetna-kompatibilita"
lang: "cz"
last_updated: "2026-11-11"
---

# Verzování API a zpětná kompatibilita

> Změna, která vypadá neškodně — přejmenování jednoho pole — dokáže odstavit integraci u zákazníka, o kterém jste nevěděli, že existuje.

Publikováno: 2026-11-11

- Přidat pole je bezpečné, přejmenovat nebo odstranit ho ne — a rozdíl je v tom, kdo změnu pocítí a kdy.
- Bez seznamu, kdo API používá, se nedá zodpovědně změnit nic.
- Novou verzi zavádějte až tehdy, když se změně nedá vyhnout; každá další verze je náklad na roky dopředu.
- Mobilní aplikaci nelze vynutit aktualizovat — staré verze API musí běžet déle, než je pohodlné.

Vývojář přejmenuje pole `zakaznik_id` na `customer_id`, protože je to konzistentnější. Testy projdou, nasadí se. Za dva dny volá zákazník, že mu přestal fungovat přenos objednávek — integraci mu dělal externí dodavatel před třemi lety a nikdo o ní nevěděl.

Toto je celé téma verzování API v jednom odstavci: **problém není ve změně, ale v tom, že o ní někdo neví.**

## Které změny jsou bezpečné

Rozdělení je jednodušší, než se zdá.

**Bezpečné** (nic nerozbijí):

- přidání nového pole do odpovědi,
- přidání **nepovinného** parametru,
- přidání nové operace,
- rozšíření číselníku o hodnotu — pokud ji odběratel nemusí znát.

**Rozbíjející** (potřebují novou verzi):

- přejmenování nebo odstranění pole,
- změna typu (`"12"` na `12`, číslo na text),
- přidání **povinného** parametru,
- změna významu existujícího pole při zachování názvu — nejzákeřnější ze všech, protože nic nespadne, jen začnou vycházet špatná čísla,
- zpřísnění validace, která do té doby procházela.

## Odběratel, o kterém nevíte

Dřív než se dá cokoli zodpovědně měnit, je třeba vědět, **kdo API volá**. Ne odhadem, ale ze záznamů: který klíč, jakou operaci, jak často, kdy naposledy.

Tento přehled má dva efekty. Ukáže integrace, na které se zapomnělo — a ukáže ty, které se už roky nepoužívají a dají se vypnout.

## Verzujte, ale střídmě

Každá verze, kterou spustíte, s vámi zůstane roky. Proto je první otázka vždy: **dá se změně vyhnout?** Často ano — nové pole vedle starého, staré ponechané a označené jako nepoužívané.

Když se vyhnout nedá, verze patří do cesty (`/v1/`, `/v2/`). Je to nejsrozumitelnější řešení a dá se přečíst z logu bez dalšího kontextu.

A pravidlo, které ušetří nejvíc bolesti: **nemějte v provozu víc než dvě verze najednou.** Tři znamenají, že se každá oprava dělá třikrát.

## Ukončení staré verze je proces, ne oznámení

Vypnutí verze má pořadí, které se vyplatí dodržet:

1. **Oznámení s datem** — ne „brzy", ale konkrétní den, ideálně půl roku dopředu.
2. **Upozornění přímo v odpovědích** staré verze, aby ho vývojář viděl i bez čtení e-mailu.
3. **Adresné oslovení** těch, kteří ji stále používají — seznam máte ze záznamů.
4. **Zkušební odstavení** na pár hodin před ostrým vypnutím. Ukáže, kdo se neozval, ale volá.
5. **Vypnutí** se srozumitelnou chybovou odpovědí, ne s tichým selháním.

## Mobilní aplikace mění pravidla

Webová aplikace se nasadí a všichni mají novou verzi. Mobilní ne — část uživatelů neaktualizuje měsíce a někteří nikdy.

Z toho vyplývá, že **staré verze API musí běžet výrazně déle**, než je pohodlné, a že aplikace potřebuje způsob, jak uživateli říct, že bez aktualizace dál nepůjde. To se musí naprogramovat dřív, než to bude třeba — jinak zůstane jediná možnost: nechat starou verzi běžet navždy.

## Chyby patří do kontraktu

Na formát chyb se zapomíná, a přitom je to část, na kterou se odběratelé spoléhají nejvíc. Pokud se změní struktura chybové odpovědi nebo kód, integrace přestanou rozlišovat mezi „zkus znovu" a „toto nikdy nevyjde".

Stejně tak do kontraktu patří limity volání — a jejich zpřísnění je rozbíjející změna, i když se nic v datech nemění.

## Dokumentace, která se nerozejde s realitou

Ručně psaná dokumentace API zastará do tří měsíců. Jediné, co dlouhodobě funguje, je **generovat ji z definice**, která je zároveň zdrojem validace — potom se nemůže rozejít s tím, co API opravdu dělá.

Souvisí to s tím, co popisujeme u [propojení firemních systémů přes API](/blog/prepojenie-firemnych-systemov-cez-api-ako-automatizovat-vymenu-dat).

## Kde začít

Dvěma věcmi, které se dají udělat tento týden: **zapnout záznam volání** s identifikací odběratele a **sepsat, co je veřejný kontrakt** — tedy která pole a operace slibujete, že nezměníte bez ohlášení. Všechno ostatní je potom rozhodnutí, ne překvapení.

Pokud stavíte API nebo řešíte existující integrace, [ozvěte se nám](/kontakt). Děláme to v rámci [vývoje na míru](/riesenia/vyvoj) — příklady v [referencích](/referencie).


---

Webová verze: https://interfase.sk/cz/novinky/verzovani-api-a-zpetna-kompatibilita
llms.txt: https://interfase.sk/llms.txt