Ako navrhnúť API pre vašu aplikáciu a partnerov
Dobré API umožní partnerovi dokončiť prácu bez hádania, čo vaša aplikácia práve urobila. Návrh preto začína významom operácií a pravidlami spolupráce. Až potom prichádzajú adresy, formáty a technológie. Ukážeme, ako pripraviť rozhranie, ktoré možno bezpečne používať, meniť aj odovzdať ďalšiemu tímu.

Predstavte si výrobcu, ktorý chce distribútorom sprístupniť dostupnosť výrobkov a príjem objednávok. Nestačí otvoriť existujúce databázové tabuľky. Distribútor potrebuje vedieť, či je dostupnosť iba orientačná, kedy sa zásoba rezervuje a ako získa konečné potvrdenie. Bez týchto odpovedí aj technicky správne prepojenie vytvára obchodné chyby.
Tento článok rieši návrh API, ktoré poskytujete ostatným. Na pripájanie existujúcich služieb nadväzuje náš sprievodca integráciou systémov. Rozdiel je v zodpovednosti: ako poskytovateľ určujete zmluvu rozhrania a nesiete náklady jej neskorších zmien.
01Začnite úlohou partnera a hranicou zodpovednosti
Spíšte niekoľko úplných scenárov: získať ponuku, vytvoriť objednávku, zistiť stav a požiadať o zrušenie. Pri každom určte vstup, výsledok a človeka rozhodujúceho o nejasnostiach. Partner môže potrebovať iný pohľad než interná aplikácia. Obchodné poznámky, nákupné ceny a interné identifikátory zamestnancov zvyčajne nepatria k jeho úlohe.
Rozlišujte čítanie informácie od záväzného príkazu. Zobrazenie skladovej dostupnosti samo nesľubuje rezerváciu. Prijatie požiadavky nemusí znamenať schválenie objednávky. Rozdiely napíšte bežným jazykom a overte s prvým budúcim používateľom ešte pred realizáciou. Výstupom má byť spoločné porozumenie procesu, nie iba zoznam adries.
02Navrhnite stabilný obchodný model, nie kópiu databázy
Pomenujte objekty a vzťahy tak, aby prežili vnútornú reorganizáciu systému. Objednávka môže obsahovať položky, doručovacie údaje a stav; nemusí odhaľovať všetky tabuľky, z ktorých vzniká. Verejné identifikátory potrebujú jasnú platnosť. Rozhodnite, či sa menia pri migrácii a ako sa rozpozná záznam, ktorý už nemožno používať.
| Oblasť | Rozhodnutie v návrhu | Čo sa inak môže pokaziť |
|---|---|---|
| Peniaze a množstvo | Mena, jednotka, presnosť a pravidlo zaokrúhľovania. | Partner zamení balenie za kus alebo cenu za inú menu. |
| Čas | Časové pásmo, formát a význam udalosti. | Dátum expedície sa zamení za okamih poslednej úpravy. |
| Prázdna hodnota | Rozdiel medzi chýbajúcim údajom, null a prázdnym textom. | Čiastočná aktualizácia nechtiac vymaže adresu. |
| Stav procesu | Povolené prechody a zodpovednosť za ich zmenu. | Partner považuje prijatie žiadosti za hotovú objednávku. |
Rovnaké definície používajte v dokumentácii, príkladoch a testoch. Pri preberaní staršej evidencie pomôže príprava migrácie dát. Nejednotný význam údajov pridaním API nezmizne, iba sa začne rýchlejšie šíriť k partnerom.
03Dohodnite zmluvu rozhrania pred implementáciou
Špecifikácia OpenAPI opisuje HTTP rozhranie spôsobom použiteľným pre ľudí aj nástroje. Zachyťte operácie, vstupy, odpovede a bezpečnostné schémy. Samotný súbor však nepreukazuje správnosť pravidiel ani súlad bežiacej služby s opisom. Potrebuje vlastníka, kontrolu zmien a overenie implementácie.
Pošlite partnerovi návrh s realistickými, bezpečne pripravenými príkladmi. Nechajte ho prejsť celý scenár pomocou skúšobného rozhrania alebo simulovanej odpovede. Sledujte miesta, kde musí doplniť nezdokumentovaný predpoklad. Ak ku každému poľu potrebuje telefonát, problém ešte nie je vyriešený. Automaticky generovaná dokumentácia má túto spoluprácu podporiť, nie nahradiť.
04Opíšte chyby a súbežné zmeny ako bežnú súčasť služby
Partner musí rozlíšiť chybný vstup, nedostatočné oprávnenie, konflikt aktuálneho stavu a dočasnú nedostupnosť. RFC 9457 ponúka štandardnú podobu strojovo čitateľných informácií o probléme. Doplňte stabilný typ problému a bezpečný identifikátor pre podporu; nevracajte zásobník chýb ani tajné interné údaje.
Dva systémy môžu upravovať rovnaký záznam. Vopred rozhodnite, ako rozpoznajú zastaranú verziu a čo urobia pri konflikte. Podmienené požiadavky opísané v HTTP sémantike umožňujú naviazať zmenu na zodpovedajúcu verziu prostriedku. Partner potom musí znovu načítať stav a rozhodnúť, nie bezmyšlienkovite prepísať novšiu prácu.
Pri príkazoch s vedľajším účinkom opíšte aj bezpečné opakovanie a dobu platnosti identifikátora požiadavky. Potvrďte, čo vrátite pri opakovaní so zmenenými dátami. Nejde o univerzálnu vlastnosť každej operácie; musí zodpovedať konkrétnemu procesu a byť overená pri preberaní.
05Oddeľte identitu partnera od oprávnenia k dátam
Každá integrácia má mať dohľadateľnú identitu a potrebný rozsah prístupu. Spoločný kľúč pre niekoľko firiem sťažuje odvolanie oprávnenia aj vyšetrovanie chyby. Server musí rozhodnúť aj o konkrétnom objekte a povolených poliach. Pravidlá sumarizuje náš článok o bezpečnosti API.
Pri odovzdávaní prístupov oddeľujte skúšobné a produkčné prostredie. Dohodnite vydanie, výmenu, zneplatnenie a vlastníka prihlasovacích údajov. Ukončenie spolupráce musí zastaviť ďalšie používanie aj nadväzné automatické úlohy. Pre prevádzkový postup nadväzuje správa tajných kľúčov a konfigurácie.

06Navrhnite objem dát, udalosti a hranice prevádzky
Zoznamy potrebujú stránkovanie, stabilné radenie a opísané správanie pri zmenách počas čítania. Pri exporte vysvetlite, či predstavuje jeden konzistentný stav alebo priebežný výber. Filtre a maximálny rozsah požiadavky navrhnite podľa skutočných úloh. Neobmedzený export nie je automaticky užitočnejšia služba.
Rozhodnite, kedy partner stav sám načítava a kedy dostane oznámenie. Udalosť môže upozorniť na zmenu, ale musí byť jasné, kde získa autoritatívny aktuálny stav. Dokumentujte opakované doručenie, poradie a dobu dostupnosti histórie. Pri dlhej operácii oddeľte prijatie práce od dokončenia a ponúknite dohľadateľný výsledok.
Limity odvodzujte od nákladov jednotlivých operácií a férového zdieľania kapacity. Počet požiadaviek nie je jediná veličina: dôležitá je súbežnosť, veľkosť odpovede aj práca na pozadí. Pri hľadaní úzkeho miesta využite postup pre výkon databázy a API.
07Verzovanie má chrániť skutočné používanie partnerov
| Zmena | Čo overiť | Ako ju pripraviť |
|---|---|---|
| Nové nepovinné pole | Či klient zvládne neznáme údaje. | Test kompatibility a doplnenie príkladov. |
| Nový stav objednávky | Či partner predpokladá uzavretý zoznam stavov. | Dohoda o správaní pri neznámej hodnote. |
| Zmena významu alebo povinnosti | Či sa nezmení platnosť doterajších požiadaviek. | Riadená migrácia alebo nová verzia rozhrania. |
| Ukončenie starej verzie | Kto ju stále používa a kto prevzal náhradu. | Oznámenie, overenie prechodu a plán vypnutia. |
Číslo verzie samo kompatibilitu nezabezpečí. Sledujte používané operácie a zmluvne dohodnite oznamovanie zmien, podporované obdobie aj kontakt pre incidenty. Termín vypnutia nemá vychádzať zo želania vývoja, ale z doloženého prechodu alebo výslovného rozhodnutia zodpovedných strán.
08Pripravte partnera na prvé spustenie aj každodennú podporu
Odovzdanie zahŕňa skúšobné dáta, prvý funkčný scenár, chybové príklady, pravidlá prístupov a kontaktné miesto. Partner potrebuje rozpoznať, či problém vznikol uňho, u vás alebo pri prenose. Identifikátor požiadavky spojí komunikáciu s prevádzkovými záznamami bez posielania celých citlivých odpovedí e-mailom.
Sledujte čas potrebný na prvý úspešný scenár a opakujúce sa otázky. Tieto signály ukazujú kvalitu návrhu lepšie než počet zverejnených operácií. Pre ďalšie zmeny určte vlastníka dokumentácie aj pravidelnej údržby. Rozhranie bez tejto zodpovednosti postupne stráca dôveryhodnosť.
Chystáte API pre distribútorov, zákazníkov alebo vlastnú aplikáciu? Pri integráciách a API od Listify začneme scenármi, dátami a hranicami zodpovednosti. Pripravte ukážku úlohy partnera a zoznam súčasných systémov; podľa nich možno vymedziť návrh aj prvú overiteľnú etapu.
09Časté otázky k návrhu partnerského API
Potrebujeme API aj pre jediného partnera?
Záleží na frekvencii, dôležitosti a automatizácii výmeny. Jednorazový prenos môže vyriešiť kontrolovaný export. Opakovaný proces s potvrdzovaním stavov zvyčajne potrebuje jasnejšie rozhranie. Najprv opíšte prácu a náklady dnešného postupu.
Je OpenAPI hotová dokumentácia?
Je to dôležitý strojovo čitateľný opis. Doplňte význam údajov, úplné scenáre, obmedzenia a pravidlá zmien. Dokumentácia musí zodpovedať nasadenej verzii a partner ju musí vedieť použiť bez neverejných predpokladov.
Má byť verejné API rovnaké ako interné?
Nemusí. Obe rozhrania môžu zdieľať pravidlá, ale partner potrebuje stabilnú zmluvu a iba povolené dáta. Zmeny internej obrazovky by nemali automaticky rozbiť distribučnú sieť.
Musíme zvoliť REST pre každé použitie?
Nie. Najprv určte spôsob práce, objem, potrebu udalostí a schopnosti partnerov. Článok opisuje najmä HTTP API. Iný štýl môže byť vhodný, ak jeho výhody vyvážia prevádzkové a integračné náklady.
Čo dodať na úvodnú konzultáciu?
Zoznam partnerov alebo typov aplikácií, hlavné scenáre, zdroje dát, očakávanú prevádzku a požadované termíny. Pridajte známe obmedzenia. Tajné kľúče ani produkčnú databázu neposielajte bežným kontaktným formulárom.