API určuje, jak jeden program žádá druhý o data nebo provedení akce. Díky němu může web založit kontakt v CRM, platební služba oznámit výsledek a mobilní aplikace načíst stav účtu. Užitečné API není jen soubor adres: je to dohoda o datech, oprávněních, chybách a pravidlech změn.
Navrhujte podle skutečných úkonů
Začněte obchodními událostmi a záznamy, které propojení opravdu potřebuje. Operace jasně pojmenujte a vracejte jen potřebné informace. Popište přijímané vstupy, možné odpovědi a chybové stavy. Dokumentace a příklady musí odpovídat nasazené službě, ne staré představě v původním zadání.
Bezpečnost je součást dohody
Ověřujte volajícího a jeho oprávnění ke konkrétnímu záznamu, nikoli jen obecnou roli. Omezujte četnost požadavků a validujte veškeré vstupy. Tajné klíče uchovávejte na důvěryhodných serverech. Zaznamenávejte úkony měnící platby, přístupová práva nebo zákaznická data.
Počítejte s nespolehlivou sítí
Požadavek může překročit časový limit, i když druhá služba už práci dokončila. Důležité zápisy navrhněte idempotentně: opakování nesmí vytvořit dvě objednávky či platby. Stanovte limity a pravidla opakování. U událostí sledujte pokusy o doručení a umožněte znovu zpracovat ty neúspěšné.
Připravte se na změny
Klienti a služby se málokdy aktualizují přesně současně. Kde to jde, zavádějte kompatibilní rozšíření; nekompatibilní změny vědomě verzujte a sledujte, kdo ještě používá staré chování. Udržované API dovolí produktu růst bez křehkých výjimek pro každé propojení.
