Jak navrhnout API pro vaši aplikaci a partnery
Dobré API umožní partnerovi dokončit práci bez hádání, co vaše aplikace právě udělala. Jeho návrh proto začíná významem operací a pravidly spolupráce. Teprve potom přicházejí adresy, formáty a technologie. Ukážeme, jak připravit rozhraní, které půjde bezpečně používat, měnit i předat dalšímu týmu.

Představte si výrobce, který chce distributorům zpřístupnit dostupnost výrobků a příjem objednávek. Nestačí otevřít současné databázové tabulky. Distributor potřebuje vědět, zda je dostupnost jen orientační, kdy se zásoba rezervuje a jak získá konečné potvrzení. Pokud tyto odpovědi chybějí, technicky správné propojení přesto vytváří obchodní chyby.
Tento článek řeší návrh API, které poskytujete ostatním. Na připojování již existujících služeb navazuje náš průvodce integrací systémů. Rozdíl je v odpovědnosti: jako poskytovatel určujete smlouvu rozhraní a nesete náklady jejích pozdějších změn.
01Začněte úkolem partnera a hranicí odpovědnosti
Sepište několik úplných scénářů: získat nabídku, vytvořit objednávku, zjistit stav a požádat o zrušení. U každého určete vstup, výsledek a člověka, který rozhoduje o nejasnostech. Partner může potřebovat jiný pohled než vaše interní aplikace. Obchodní poznámky, nákupní ceny a interní identifikátory zaměstnanců obvykle nejsou součástí jeho úkolu.
Rozlišujte čtení informace od závazného příkazu. Zobrazení skladové dostupnosti samo neslibuje rezervaci. Přijetí požadavku nemusí znamenat schválení objednávky. Tyto rozdíly napište běžným jazykem a ověřte s prvním budoucím uživatelem ještě před realizací. Výstupem má být sdílené porozumění procesu, nikoli jen seznam adres.
02Navrhněte stabilní obchodní model, ne kopii databáze
Pojmenujte objekty a vztahy tak, aby přežily vnitřní reorganizaci systému. Objednávka může obsahovat položky, doručovací údaje a stav; nemusí odhalovat všechny tabulky, ze kterých vzniká. Veřejné identifikátory potřebují jasnou platnost. Rozhodněte, zda se mění při migraci a jak se pozná záznam, který již nelze používat.
| Oblast | Rozhodnutí v návrhu | Co se jinak může pokazit |
|---|---|---|
| Peníze a množství | Měna, jednotka, přesnost a pravidlo zaokrouhlení. | Partner zamění balení za kus nebo cenu za jinou měnu. |
| Čas | Časové pásmo, formát a význam události. | Datum expedice se zamění za okamžik poslední úpravy. |
| Prázdná hodnota | Rozdíl mezi chybějícím údajem, null a prázdným textem. | Částečná aktualizace nechtěně smaže adresu. |
| Stav procesu | Povolené přechody a odpovědnost za jejich změnu. | Partner považuje přijetí žádosti za hotovou objednávku. |
Stejné definice používejte v dokumentaci, příkladech a testech. Pokud přebíráte starší evidenci, pomůže příprava migrace dat. Nejednotný význam údajů se přidáním API neztratí, pouze se začne rychleji šířit k partnerům.
03Dohodněte smlouvu rozhraní dříve než implementaci
Specifikace OpenAPI popisuje HTTP rozhraní způsobem použitelným pro lidi i nástroje. Zachyťte operace, vstupy, odpovědi a bezpečnostní schémata. Samotný soubor však neprokazuje správnost pravidel ani soulad běžící služby s popisem. Potřebuje vlastníka, kontrolu změn a ověření implementace.
Pošlete partnerovi návrh s realistickými, bezpečně připravenými příklady. Nechte ho projít jeden celý scénář pomocí zkušebního rozhraní nebo simulované odpovědi. Sledujte místa, kde musí doplnit nedokumentovaný předpoklad. Pokud ke každému poli potřebuje telefonát, problém ještě není vyřešený. Automaticky vygenerovaná dokumentace má tuto spolupráci podpořit, ne nahradit.
04Popište chyby a souběžné změny jako běžnou součást služby
Partner musí rozlišit chybný vstup, nedostatečné oprávnění, konflikt aktuálního stavu a dočasnou nedostupnost. RFC 9457 nabízí standardní podobu strojově čitelných informací o problému. Doplňte stabilní typ problému a bezpečný identifikátor pro podporu; nevracejte zásobník chyb ani tajné interní údaje.
Dva systémy mohou upravovat stejný záznam. Předem rozhodněte, jak poznají zastaralou verzi a co udělají při konfliktu. Podmíněné požadavky popsané v HTTP sémantice umožňují navázat změnu na odpovídající verzi prostředku. Partner pak musí znovu načíst stav a rozhodnout, nikoli bezmyšlenkovitě přepsat novější práci.
U příkazů s vedlejším účinkem popište také bezpečné opakování a dobu platnosti identifikátoru požadavku. Potvrďte, co vrátíte při opakování se změněnými daty. Nejde o univerzální vlastnost každé operace; musí odpovídat konkrétnímu procesu a být ověřena v přejímacích scénářích.
05Oddělte identitu partnera od oprávnění k datům
Každá integrace má mít dohledatelnou identitu a potřebný rozsah přístupu. Sdílený klíč pro několik firem ztěžuje odvolání oprávnění i vyšetření chyby. Server musí rozhodnout také o konkrétním objektu a povolených polích. Pravidla shrnuje náš článek o bezpečnosti API.
Při předávání přístupů rozlišujte zkušební a produkční prostředí. Dohodněte vydání, výměnu, zneplatnění a vlastníka přihlašovacích údajů. Ukončení spolupráce musí zastavit další použití i navazující automatické úlohy. Pro provozní postup navazuje správa tajných klíčů a konfigurace.

06Navrhněte objem dat, události a hranice provozu
Seznamy potřebují stránkování, stabilní řazení a popsané chování při změnách během čtení. U exportu vysvětlete, zda představuje jeden konzistentní stav, nebo průběžný výběr. Filtry a maximální rozsah požadavku navrhněte podle skutečných úloh. Neomezený export není automaticky užitečnější služba.
Rozhodněte, kdy partner stav sám načítá a kdy dostane oznámení. Událost může upozornit na změnu, ale musí být jasné, kde získat autoritativní aktuální stav. Dokumentujte opakované doručení, pořadí a dobu dostupnosti historie. U dlouhé operace oddělte přijetí práce od jejího dokončení a nabídněte dohledatelný výsledek.
Limity odvozujte od nákladů jednotlivých operací a férového sdílení kapacity. Počet požadavků není jediná veličina: důležitá je souběžnost, velikost odpovědi i práce na pozadí. Pro hledání úzkého místa využijte postup pro výkon databáze a API.
07Verzování má chránit skutečné používání partnerů
| Změna | Co ověřit | Jak ji připravit |
|---|---|---|
| Nové nepovinné pole | Zda klient zvládne neznámé údaje. | Test kompatibility a doplnění příkladů. |
| Nový stav objednávky | Zda partner předpokládá uzavřený seznam stavů. | Dohoda o chování při neznámé hodnotě. |
| Změna významu nebo povinnosti | Zda se nezmění platnost dosavadních požadavků. | Řízená migrace nebo nová verze rozhraní. |
| Ukončení staré verze | Kdo ji stále používá a kdo převzal náhradu. | Oznámení, ověření přechodu a plán vypnutí. |
Číslo verze samo kompatibilitu nezajistí. Sledujte používané operace a smluvně dohodněte oznamování změn, podporované období i kontakt pro incidenty. Termín vypnutí nemá vycházet z přání vývoje, ale z doloženého přechodu nebo výslovného rozhodnutí odpovědných stran.
08Připravte partnera na první spuštění i každodenní podporu
Předání zahrnuje zkušební data, první funkční scénář, chybové příklady, pravidla přístupů a kontaktní místo. Partner potřebuje poznat, zda problém vznikl u něj, u vás, nebo při přenosu. Identifikátor požadavku propojí komunikaci s provozními záznamy, aniž by podpora musela posílat celé citlivé odpovědi e-mailem.
Sledujte čas potřebný k prvnímu úspěšnému scénáři a opakující se dotazy. Tyto signály ukazují kvalitu návrhu lépe než počet zveřejněných operací. Pro další změny určete vlastníka dokumentace i pravidelné údržby. Rozhraní bez této odpovědnosti postupně ztrácí důvěryhodnost.
Chystáte API pro distributory, zákazníky nebo vlastní aplikaci? U integrací a API od Listify začneme scénáři, daty a hranicemi odpovědnosti. Připravte ukázku úkolu partnera a seznam současných systémů; podle nich lze vymezit návrh i první ověřitelnou etapu.
09Časté otázky k návrhu partnerského API
Potřebujeme API i pro jediného partnera?
Záleží na četnosti, důležitosti a automatizaci výměny. Jednorázový přenos může vyřešit kontrolovaný export. Opakovaný proces s potvrzováním stavů obvykle potřebuje jasnější rozhraní. Nejdříve popište práci a náklady dnešního postupu.
Je OpenAPI hotová dokumentace?
Je to důležitý strojově čitelný popis. Doplňte význam údajů, úplné scénáře, omezení a pravidla změn. Dokumentace musí odpovídat nasazené verzi a partner ji musí dokázat použít bez neveřejných předpokladů.
Má být veřejné API stejné jako interní?
Nemusí. Obě rozhraní mohou sdílet pravidla, ale partner potřebuje stabilní smlouvu a jen povolená data. Změny interní obrazovky by neměly automaticky rozbít distribuční síť.
Musíme vybrat REST pro každé použití?
Ne. Nejprve určete způsob práce, objem, potřebu událostí a schopnosti partnerů. Článek popisuje zejména HTTP API. Jiný styl může být vhodný, pokud jeho výhody vyváží provozní a integrační náklady.
Co dodat na úvodní konzultaci?
Seznam partnerů nebo typů aplikací, hlavní scénáře, zdroje dat, očekávaný provoz a požadované termíny. Přidejte známá omezení. Tajné klíče ani produkční databázi běžným kontaktním formulářem neposílejte.