Navrhujete-li rest api s dlouhým životním cyklem, musíte od začátku počítat s tím, že datový model se bude vyvíjet. Základním pravidlem je verzování celého rozhraní, a to ideálně hned od prvního dne. Nechte verzi v URL cestě, například /v1/uzivatele, a nikdy neměňte existující endpoint pod stejnou verzí. Pokud potřebujete přidat nový povinný atribut do odpovědi, vytvořte novou verzi. Mnohem častěji ale nastane situace, kdy potřebujete rozšířit stávající zdroj. https://vyvojarska.cz/ takovém případě postupujte vždy aditivně: nové pole přidejte jako volitelné a v dokumentaci jasně specifikujte, od které verze je dostupné a jaká je jeho výchozí hodnota. Vyhněte se používání složených typů jako pole objektů s pevnou strukturou, místo toho preferujte mapy klíč-hodnota nebo pole s identifikátory, která lze snadno rozšířit bez porušení zpětné kompatibility.
Druhým klíčovým principem je navrhnout zdroje jako stabilní entity s jednoznačnými identifikátory. Používejte UUID místo autoinkrementálních čísel, protože UUID vám umožní migrovat data mezi systémy a měnit interní klíče bez dopadu na klienty. Vyhněte se vnořování celých objektů do odpovědí, pokud to není nezbytně nutné. Místo toho vracejte odkazy na související zdroje (například /v1/uzivatele/123/objednavky), a to i za cenu vyššího počtu požadavků. Tím dosáhnete toho, že změna vnitřní struktury podřízeného modelu neovlivní hlavní odpověď. Dále používejte expand parametry pro volitelné rozšíření, nikoliv pro povinná pole. Vždy myslete na to, že každý nový atribut v odpovědi může znamenat pro starší klienty neočekávané chování, proto ho uvádějte až v nové minoritní verzi a starou verzi udržujte beze změny.
Poslední rada se týká zpracování vstupů a chybových stavů. Nikdy neočekávejte, že klient pošle přesně to, co jste definovali. Místo striktního validování celého objektu přijímejte neznámá pole a ignorujte je, nikoliv vracet chybu. Pro povinná pole používejte sémantické názvy, které odrážejí business význam, ne technickou implementaci – pokud později změníte název sloupce v databázi, API zůstane stabilní. Chybové odpovědi vracejte s jednoznačným kódem a strojově čitelnou zprávou ve strukturovaném formátu, který obsahuje pole pro identifikátor problému, nikoliv jen lidský text. Tím zajistíte, že klienti mohou na změny reagovat programově. Dodržováním těchto zásad – aditivní evoluce, stabilní identifikátory a tolerantní zpracování – vytvoříte rest api, které přežije roky vývoje bez nutnosti rozbíjet existující integrace.