5 soļi veiksmīgas api izveidē

Tas ir programmatūras izstrādes raksturs. Izstrādātāji izveido programmatūru, paturot prātā galalietotāju. Tas šķiet diezgan vienkārši, taču dažreiz šie lietotāji ir arī citi izstrādātāji. Viņiem nav vajadzīgas lietas, kas ir sadalītas. Viņiem nav vajadzīga pat vienkāršība. Viņi vēlas tikai piekļuvi - veids, kā integrēt programmatūru ar savējo. Šeit nāk API (lietojumprogrammu programmēšanas saskarne). Es ceru izcelt piecas darbības, kuras varat veikt, lai izveidotu veiksmīgu API.

Izpildi savu mājasdarbu

Runājot par programmatūras izstrādi, neviens no mums nevēlas no jauna izgudrot riteni. Šajā brīdī gandrīz visiem lielajiem tīmekļa uzņēmumiem ir API viņu programmatūras produktiem. Izpētiet šīs API un mēģiniet izvēlēties dažādus dizaina lēmumus, kas tika pieņemti to veidošanā.

Tur ir daudz dažādu tehnoloģiju, taču lielākajā daļā jūsu redzēto API tiks izmantota RESTful saskarne vai SOAP. Ja atrodaties pie žoga, kuru API saskarni izmantosit, es ieteiktu izvēlēties RESTful pieeju, izmantojot HTTP protokolu. Tas ir vienkāršāks nekā SOAP, tas šobrīd ir populārāks, un ar to būs vieglāk sākt strādāt, izmantojot Web balstītu programmatūras produktu.

Esiet konsekventi

Viena no lietām, ko izstrādātāji novērtē visvairāk, ir konsekvence. Cita starpā tas ietver adresējamību, ievades argumentus, izvades formātus un kļūdu apstrādi.

Izmantojot RESTful pieeju, ir daudz dažādu URI nosaukšanas shēmu. Katram no tiem ir savi atbalstītāji, tāpēc vienkārši izvēlieties vienu un pieturieties pie tā. Tas pats attiecas uz ievades un izvades struktūru. Lielākā daļa API atbalsta XML un JSON kā ievades un izvades formātu izmantošanu. Es ieteiktu atbalstīt abus, bet izvēlēties noklusējuma formātu.

Ievadei jūsu ievades prasības ir konsekventi jānorāda, un tām ir jābūt jēgai jūsu izveidotā API zvana kontekstā. Izvadei pārliecinieties, vai izmantojat kopīgus datu struktūras izkārtojumus. Ja jūs iesaiņojat viena API zvana izvadi XML tagu, apsveriet iespēju to darīt ar citiem zvaniem.

Ierasta prakse ir iekļaut sava veida statusa karogu izejas datos, ko nosūtāt atpakaļ klientam. Izmantojot RESTful API pieeju, tas jādara, izmantojot HTTP statusa kodus. Piemēram, ja jūs tikko apstrādājāt PUT pieprasījumu esošā datu objektā, atbildē iekļautais HTTP statusa kods mainīsies atkarībā no pieprasījuma rezultāta.

Patvaļīga karoga vietā, kas norāda zvana statusu, standarta "200 OK" statusa kodu var izmantot, lai norādītu uz pieprasījuma sekmīgu izpildi, savukārt statusa kodu "400 Bad Request" varētu izmantot, lai norādītu, ka pieprasījums ir izpildīts. kroplīgi. Ir diezgan daudz HTTP statusa kodu, kurus var izmantot dažādās situācijās.

Izmantojiet OAuth

Lielākā daļa programmatūras produktu būs saistīta ar sava veida lietotāja autentifikāciju, lai piekļūtu šī lietotāja aizsargātajiem resursiem. Runājot par API, slikta prakse ir, ja klients vāc lietotāja akreditācijas datus, lai tos nosūtītu uz jūsu serveri. Šajā vietā ienāk OAuth.

OAuth sniedz daudz priekšrocību salīdzinājumā ar trešo personu lietotājvārdu / paroli autentificēšanu. Pirmkārt, klientam nekad nav piekļuves lietotāja akreditācijas datiem. Lietotājs tiek novirzīts uz jūsu serveri, kad viņš / viņa piesakās. Pēc tam, kad lietotājs piesakās jūsu vietnē, viņš tiek novirzīts atpakaļ uz klientu, kur klients saņems piekļuves pilnvaru, lai to izmantotu turpmākos aizsargāto resursu pieprasījumos.

Vēl viens svarīgs OAuth izmantošanas ieguvums ir lietotāja spēja jebkurā laikā atcelt piekļuvi klientam. Ja lietotājs nolemj, ka kāda iemesla dēļ viņi vairs nevēlas, lai klients varētu piekļūt aizsargātajiem resursiem viņa vārdā, viņš vienkārši dodas uz jūsu izveidoto saskarni un atceļ klienta piekļuvi.

Sāciet agri

Viena no vissvarīgākajām lietām, ko varat darīt, lai jūsu API būtu veiksmīga, ir sākt agri. Rakstot šo funkciju, lai izveidotu kādu ierakstu datu bāzē, dodieties uz priekšu un veltiet papildu laiku un uzrakstiet tam API saskarni.

Uzrakstiet labu dokumentāciju

Nekas nenogalina API ātrāk, nekā ja tam nav labas dokumentācijas. Lai gan daži izstrādātāji var izmantot vāji dokumentētu API un izdomāt, kā tam vajadzētu darboties, vairums to nevēlas.

Jums jādokumentē katrs pieejamais API zvans un jāklasificē savi API zvani pēc to veida, kurā viņi darbojas. Līdztekus pašu API izsaukumu parametru dokumentēšanai jums sistemātiski jādefinē nepieciešamie un izvēles ievades argumenti, kā arī izejas datu struktūras. Ievades argumentos jāiekļauj noklusējuma vērtība, ja tāda ir, un jānorāda arī sagaidāmais datu formāts, piemēram, skaitlis vai virkne. Visbeidzot, katram API zvanam vajadzētu būt kļūdu apstākļu un statusa kodu sarakstam.

Lai noapaļotu dokumentāciju, katrā API zvanā noteikti iekļaujiet vienu vai divus parastos ievades un izvades scenāriju piemērus.

API izstrāde: saglabājiet to vienkāršā veidā

Lai arī var šķist, ka API izstrāde ir sarežģīts darbs, pati API ideja nav jauna koncepcija, un par katru šeit apskatīto tēmu ir pieejams liels daudzums pieejamo dokumentu. Tikai pārliecinieties, ka izmantojat labo praksi, kur to varat atrast, un nodrošiniet konsekventu, labi dokumentētu saskarni.