Co je návrh API?
Návrh API je rozhodnutí o tom, co vaše API nabízí a jak ho ostatní vývojáři volají, ještě než napíšete samotnou implementaci. Patří sem názvy koncových bodů (endpointů), podoba dat, která posíláte a přijímáte, chyby, které vracíte, a pravidla, jak to všechno časem měníte. Kód za API můžete kdykoli přepsat. Návrh je slib, který dáváte všem, kdo na vašem API staví, a porušit takový slib stojí draho.
Lidsky řečeno
Návrh API si představte jako rozmístění ovládacích prvků v autě. Motor se může změnit, ale volant, pedály i budíky musí být tam, kde je každý řidič čeká. S dobrým API je to stejné. Kdo už používal něco podobného, měl by uhodnout, jak funguje to vaše, i bez čtení návodu. Návrh je ta část, které se „řidič“ reálně dotýká, takže si zaslouží víc péče než to, co je schované pod kapotou.
Co dobrý návrh API zahrnuje
- Jasné a jednotné názvy. Zdroje jsou podstatná jména (
/faktury,/uzivatele) a stejná věc se všude jmenuje stejně. Vývojář by měl po dvou endpointech uhodnout, jak se jmenuje další. - Předvídatelnou strukturu. Používejte standardní HTTP metody a stavové kódy tak, jak se mají.
GETčte,POSTvytváří,404znamená nenalezeno. Nevymýšlejte si vlastní významy. - Poctivé chyby. Když něco selže, řekněte co a jak to spravit. Strojově čitelný formát chyb, třeba RFC 7807 (problem details), ušetří volajícímu hodiny hádání.
- Zapsanou smlouvu. Popište API ve specifikaci OpenAPI. Stane se jediným zdrojem pravdy, ze kterého vznikne dokumentace, klientské knihovny i testy.
- Plán verzování. Hned na začátku se rozhodněte, jak budete přidávat pole a rušit stará, aniž byste rozbili stávající volání.
Proč na tom záleží
Kvalita API rozhoduje o tom, jak rychle na něm dokážou stavět ostatní týmy. Jasné a jednotné API se rychle uchytí a generuje málo tiketů na podporu. Nepřehledné API lidé obcházejí, používají špatně nebo ho opustí a z každé integrace se stane série dotazů sem a tam. V DX Heroes je návrh API klíčovou součástí developer experience. Čím srozumitelnější API je, tím rychleji se partner dostane k prvnímu úspěšnému volání.
Na co si dát pozor
- Návrh až po napsání kódu. Když API kopíruje vaše databázové tabulky nebo vnitřní kód, prozrazuje rozhodnutí, která měla zůstat skrytá, a později se těžko mění.
- Změny, které rozbíjejí, bez verzí. Přejmenování pole nebo změna podoby odpovědi potichu rozbije každého volajícího. Místo toho přidávejte, označujte jako zastaralé a odebírejte podle jasného plánu.
- Nejednotnost. Jeden endpoint vrací
userId, druhýuser_id. I drobné rozdíly nutí vývojáře číst dokumentaci ke každému volání. - Únik vnitřností přes chyby. Výpisy zásobníku a syrové databázové hlášky volajícího matou a odhalují, jak váš systém funguje. Vracejte čisté a zdokumentované chyby.
Související články
- Co je API? - Základní myšlenka, jak si software říká o data a akce.
- Zlepšete adopci API s OpenAPI specifikací - Standard, jak smlouvu vašeho API zapsat.
- SDK vs. API - Jak sada nástrojů a rozhraní hrají různé role.
Chcete být o krok napřed?
Nenechte si utéct naše nejlepší postřehy. Žádný spam, jen praktické analýzy, pozvánky na exkluzivní eventy a shrnutí podcastů přímo do vaší schránky.