Tartalomjegyzék:
- Csináld meg a leckét
- Légy következetes
- Használja az OAuth alkalmazást
- Korán kezdje
- Írjon jó dokumentációt
- API fejlesztés: tartsa egyszerűen
Ez a szoftverfejlesztés természete. A fejlesztők a végfelhasználót szem előtt tartva készítik a szoftvert. Nagyon egyszerűnek tűnik, de néha ezek a felhasználók fejlesztők is. Nekik nincs szükségük lebontott dolgokra. Nincs szükségük még az egyszerűségre sem. Csak hozzáférést akarnak - a szoftver integrálásának egyik módját. Itt jön létre egy API (alkalmazásprogramozási felület). Remélem, hogy kiemelem öt lépést, amelyet megtehetsz a sikeres API létrehozásához.
Csináld meg a leckét
A szoftverfejlesztés kapcsán egyikünk sem akarja újra feltalálni a kereket. Ezen a ponton szinte minden nagy webes cég rendelkezik API-kkal szoftvertermékeihez. Tanulja meg ezeket az API-kat, és próbálja meg átgondolni azokat a különféle tervezési döntéseket, amelyek a létrehozásukhoz szükségesek voltak.
Sokféle technológia létezik, de a látott API-k többsége RESTful felületet vagy SOAP-t fog használni. Ha azon a kerítésen áll, hogy melyik API-felületet fogja használni, azt javaslom, hogy a RESTful megközelítést használja a HTTP protokoll használatával. Egyszerűbb, mint a SOAP, jelenleg népszerűbb, és könnyebb lesz az induláshoz, ha webes szoftvert használ.
Légy következetes
Az egyik dolog, amelyet a fejlesztők a legjobban értékelnek, a következetesség. Ez magában foglalja többek között a címezhetőséget, a bemeneti argumentumokat, a kimeneti formátumokat és a hibakezelést.
Ha egy RESTful megközelítést használ, sok különböző URI elnevezési séma létezik. Mindegyiknek megvan a támogatója, tehát csak válasszon egyet, és maradjon vele. Ugyanez vonatkozik a bemeneti és a kimeneti struktúrára. A legtöbb API támogatja az XML és a JSON használatát bemeneti és kimeneti formátumként. Azt javaslom, hogy támogassuk mindkettőt, de válasszunk egy alapértelmezett formátumot.
A bevitelhez a bemeneti követelményeket következetesen meg kell nevezni, és azoknak értelemszerűnek kell lenniük a végrehajtott API-hívás összefüggésében. A kiadáshoz győződjön meg arról, hogy az általános adatszerkezet-elrendezéseket használja. Ha egy API-hívás kimenetét csomagolja be a
Általános gyakorlat, hogy valamilyen állapotjelzőt tartalmaznak az ügyféllel visszaküldött kimeneti adatokba. RESTful API megközelítés használata esetén ezt HTTP állapotkódok használatával kell megtenni. Például, ha csak egy PUT-kérelmet dolgozott fel egy meglévő adatobjektumon, akkor a válaszába bevitt HTTP-állapotkód a kérés eredményétől függ.
A hívás állapotát jelző tetszőleges jelző helyett egy szabványos "200 OK" állapotkód használható a kérés sikerességének jelzésére, míg a "400 rossz kérés" állapotkód használható a kérés jelzésére. torz. Nagyon sok HTTP állapotkód használható különféle helyzetekben.
Használja az OAuth alkalmazást
A legtöbb szoftvertermék valamilyen felhasználói hitelesítést igényel, hogy hozzáférjen a felhasználó védett erőforrásaihoz. Ha az API-kat illeti, akkor rossz gyakorlat az, ha az ügyfél összegyűjti a felhasználói hitelesítő adatokat, hogy eljuttassa a kiszolgálóra. Itt jön be az OAuth.
Az OAuth számos előnyt kínál a harmadik féltől származó felhasználónév / jelszó hitelesítéshez képest. Mindenekelőtt az ügyfél soha nem fér hozzá a felhasználó hitelesítő adataihoz. A felhasználót átirányítja a szerverre, amikor bejelentkezik. Miután a felhasználó bejelentkezett a webhelyére, visszakerül az ügyféllel, ahol az ügyfél hozzáférési jogkivonatot kap, amelyet felhasználhat a későbbiekben a védett erőforrások igényléséhez.
Az OAuth használatának másik fontos előnye, hogy a felhasználó bármikor visszavonhatja az ügyfél hozzáférését. Ha a felhasználó úgy dönt, hogy bármilyen okból már nem akarja, hogy az ügyfél hozzáférhessen a védett erőforrásokhoz a nevükben, akkor egyszerűen felkeres egy felületet, amelyet létrehozott, és megszünteti az ügyfél hozzáférését.
Korán kezdje
Az API legfontosabb sikereinek egyik legfontosabb eleme a korai indítás. Amikor ezt a funkciót írja be, hogy valamilyen bejegyzést hozzon létre az adatbázisban, menjen tovább, és szánjon rá több időt, és írjon hozzá egy API-felületet.Írjon jó dokumentációt
Semmi sem öl meg gyorsabban az API-t, mint ha nincs megfelelő dokumentáció. Míg egyes fejlesztők elkészíthetnek egy rosszul dokumentált API-t, és kitalálhatják, hogyan kell működni, a legtöbb nem akarja.
Dokumentálnia kell minden rendelkezésre álló API-hívást, és kategorizálnia kell az API-hívásokat az általuk alkalmazott adatok típusa szerint. Az API-hívások végpontjainak dokumentálásával együtt szisztematikusan meg kell határoznia a szükséges és opcionális bemeneti argumentumokat, valamint a kimeneti adatszerkezeteket. A bemeneti argumentumoknak fel kell sorolniuk egy alapértelmezett értéket, ha van ilyen, és meg kell jelölniük a várható adatformátumot, például egy számot vagy karakterláncot. Végül, minden API-hívásnak tartalmaznia kell a hibafeltételek és az állapotkódok listáját.
A dokumentáció lekerekítéséhez feltétlenül tartalmazzon egy vagy két példát az egyes API-hívások általános bemeneti és kimeneti forgatókönyveihez.
API fejlesztés: tartsa egyszerűen
Noha úgy tűnhet, hogy egy API kidolgozása bonyolult törekvés, önmagában az API elképzelése nem új koncepció, és minden egyes témában, amelyekkel itt foglalkoztunk, rengeteg rendelkezésre álló dokumentum található. Csak ügyeljen arra, hogy a bevált gyakorlatokat megtalálja, ahol megtalálhatja őket, és biztosítson egy következetes, jól dokumentált felületet.
