Přeskočit na obsah
Systémy na míru

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.

Jak navrhnout API pro vaši aplikaci a partnery

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.

OblastRozhodnutí v návrhuCo 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á hodnotaRozdíl mezi chybějícím údajem, null a prázdným textem.Částečná aktualizace nechtěně smaže adresu.
Stav procesuPovolené 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.

Pět kroků od úkolu partnera k udržovanému API
Návrh pokračuje i po spuštění: změny rozhraní potřebují komunikaci, ověření a odpovědného vlastníka.

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ěnaCo ověřitJak ji připravit
Nové nepovinné poleZda klient zvládne neznámé údaje.Test kompatibility a doplnění příkladů.
Nový stav objednávkyZda partner předpokládá uzavřený seznam stavů.Dohoda o chování při neznámé hodnotě.
Změna významu nebo povinnostiZda se nezmění platnost dosavadních požadavků.Řízená migrace nebo nová verze rozhraní.
Ukončení staré verzeKdo 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.

Probrat návrh API

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.

Tým LISTIFYWeby, aplikace a marketing z Prahy od roku 2008

Další články

Všechny články →

Sdílet stránku

E-mailem

Máte nápad?

V krátkém hovoru zjistíme, co potřebujete, a navrhneme další krok. Pak dostanete nabídku s pevnou cenou a termínem.

+420 771 166 199Po až Pá 8:30 až 16:00 · info@listify.cool

Kdy vám máme zavolat?

Vyberte den a časové rozmezí. Zavoláme my, hovor trvá zhruba 15 minut.

Den