---
title: "Verzionovanie API a spätná kompatibilita"
description: "Zmena, ktorá vyzerá neškodne — premenovanie jedného poľa — dokáže odstaviť integráciu u zákazníka, o ktorom ste nevedeli, že existuje."
canonical: "https://interfase.sk/sk/novinky/verzionovanie-api-a-spatna-kompatibilita"
lang: "sk"
last_updated: "2026-11-11"
---

# Verzionovanie API a spätná kompatibilita

> Zmena, ktorá vyzerá neškodne — premenovanie jedného poľa — dokáže odstaviť integráciu u zákazníka, o ktorom ste nevedeli, že existuje.

Publikované: 2026-11-11

- Pridať pole je bezpečné, premenovať alebo odstrániť ho nie — a rozdiel je v tom, kto zmenu pocíti a kedy.
- Bez zoznamu, kto API používa, sa nedá zodpovedne zmeniť nič.
- Novú verziu zavádzajte až vtedy, keď sa zmene nedá vyhnúť; každá ďalšia verzia je náklad na roky dopredu.
- Mobilná aplikácia sa nedá vynútiť aktualizovať — staré verzie API musia bežať dlhšie, než je pohodlné.

Vývojár premenuje pole `zakaznik_id` na `customer_id`, lebo to je konzistentnejšie. Testy prejdú, nasadí sa. O dva dni volá zákazník, že mu prestal fungovať prenos objednávok — integráciu mu robil externý dodávateľ pred tromi rokmi a nikto o nej nevedel.

Toto je celá téma verzionovania API v jednom odseku: **problém nie je v zmene, ale v tom, že o nej niekto nevie.**

## Ktoré zmeny sú bezpečné

Rozdelenie je jednoduchšie, než sa zdá.

**Bezpečné** (nič nerozbijú):

- pridanie nového poľa do odpovede,
- pridanie **nepovinného** parametra,
- pridanie novej operácie,
- rozšírenie číselníka o hodnotu — pokiaľ ju odberateľ nemusí poznať.

**Rozbíjajúce** (potrebujú novú verziu):

- premenovanie alebo odstránenie poľa,
- zmena typu (`"12"` na `12`, číslo na text),
- pridanie **povinného** parametra,
- zmena významu existujúceho poľa pri zachovaní názvu — najzákernejšia zo všetkých, lebo nič nespadne, len začnú vychádzať zlé čísla,
- sprísnenie validácie, ktorá dovtedy prechádzala.

## Odberateľ, o ktorom neviete

Predtým než sa dá čokoľvek zodpovedne meniť, treba vedieť, **kto API volá**. Nie odhadom, ale zo záznamov: ktorý kľúč, akú operáciu, ako často, kedy naposledy.

Tento prehľad má dva efekty. Ukáže integrácie, na ktoré sa zabudlo — a ukáže tie, ktoré sa už roky nepoužívajú a dajú sa vypnúť.

## Verzionujte, ale striedmo

Každá verzia, ktorú spustíte, s vami zostane roky. Preto je prvá otázka vždy: **dá sa zmene vyhnúť?** Často áno — nové pole vedľa starého, staré ponechané a označené ako nepoužívané.

Keď sa vyhnúť nedá, verzia patrí do cesty (`/v1/`, `/v2/`). Je to najzrozumiteľnejšie riešenie a dá sa prečítať z logu bez ďalšieho kontextu.

A pravidlo, ktoré ušetrí najviac bolesti: **nemajte v prevádzke viac než dve verzie naraz.** Tri znamenajú, že sa každá oprava robí trikrát.

## Ukončenie starej verzie je proces, nie oznam

Vypnutie verzie má poradie, ktoré sa oplatí dodržať:

1. **Oznámenie s dátumom** — nie „čoskoro", ale konkrétny deň, ideálne pol roka dopredu.
2. **Upozornenie priamo v odpovediach** starej verzie, aby ho vývojár videl aj bez čítania e-mailu.
3. **Adresné oslovenie** tých, ktorí ju stále používajú — zoznam máte zo záznamov.
4. **Skúšobné odstavenie** na pár hodín pred ostrým vypnutím. Ukáže, kto sa neozval, ale volá.
5. **Vypnutie** so zrozumiteľnou chybovou odpoveďou, nie s tichým zlyhaním.

## Mobilná aplikácia mení pravidlá

Webová aplikácia sa nasadí a všetci majú novú verziu. Mobilná nie — časť používateľov neaktualizuje mesiace a niektorí nikdy.

Z toho vyplýva, že **staré verzie API musia bežať výrazne dlhšie**, než je pohodlné, a že aplikácia potrebuje spôsob, ako používateľovi povedať, že bez aktualizácie ďalej nepôjde. To sa musí naprogramovať skôr, než to bude treba — inak zostane jediná možnosť: nechať starú verziu bežať navždy.

## Chyby patria do kontraktu

Na formát chýb sa zabúda, a pritom je to časť, na ktorú sa odberatelia spoliehajú najviac. Ak sa zmení štruktúra chybovej odpovede alebo kód, integrácie prestanú rozlišovať medzi „skús znova" a „toto nikdy nevyjde".

Rovnako do kontraktu patria limity volaní — a ich sprísnenie je rozbíjajúca zmena, aj keď sa nič v dátach nemení.

## Dokumentácia, ktorá sa nerozíde s realitou

Ručne písaná dokumentácia API zastará do troch mesiacov. Jediné, čo dlhodobo funguje, je **generovať ju z definície**, ktorá je zároveň zdrojom validácie — potom sa nemôže rozísť s tým, čo API naozaj robí.

Súvisí to s tým, čo popisujeme pri [prepojení firemných systémov cez API](/blog/prepojenie-firemnych-systemov-cez-api-ako-automatizovat-vymenu-dat).

## Kde začať

Dvomi vecami, ktoré sa dajú spraviť tento týždeň: **zapnúť záznam volaní** s identifikáciou odberateľa, a **spísať, čo je verejný kontrakt** — teda ktoré polia a operácie sľubujete, že nezmeníte bez ohlásenia. Všetko ostatné je potom rozhodnutie, nie prekvapenie.

Ak staviate API alebo riešite existujúce integrácie, [ozvite sa nám](/kontakt). Robíme to v rámci [vývoja na mieru](/riesenia/vyvoj) — príklady v [referenciách](/referencie).


---

Webová verzia: https://interfase.sk/sk/novinky/verzionovanie-api-a-spatna-kompatibilita
llms.txt: https://interfase.sk/llms.txt