5 корака за стварање успешне апи

То је природа развоја софтвера. Програмери стварају софтвер са циљем крајњег корисника. Чини се прилично једноставно, али понекад су ти корисници такође колеге програмери. Не требају им ствари разбијене. Не треба им ни једноставност. Све што желе је приступ - начин да интегришу свој софтвер са својим. Овде долази АПИ (програмско сучеље за апликације). Надам се да ћу истакнути пет корака које можете предузети како бисте створили успешан АПИ.

Уради свој домаћи задатак

Када је у питању развој софтвера, нико од нас не жели измислити точак. У овом тренутку скоро све велике веб компаније имају АПИ за своје софтверске производе. Проучите ове АПИ-је и покушајте да потражите различите дизајнерске одлуке које су креирале у њиховом креирању.

Постоји много различитих технологија вани, али већина АПИ-ја које ћете видети користиће или РЕСТфул интерфејс или СОАП. Ако сте на огради за АПИ интерфејс који ћете користити, предлажем вам да кренете са РЕСТфул приступом користећи ХТТП протокол. Једноставнији је од СОАП-а, тренутно је популарнији и биће лакше започети са коришћењем софтверског производа заснованог на Вебу.

Будите доследни

Једна од ствари која програмери највише цене је конзистентност. То између осталог укључује и адресибилност, улазне аргументе, формате излаза и руковање грешкама.

Када се користи РЕСТфул приступ, постоји много различитих схема именовања УРИ. Свака од њих има своје присталице, зато их само одаберите и држите се тога. Исто је и са структуром улаза и излаза. Већина АПИ-ја подржава КСМЛ и ЈСОН као улазне и излазне формате. Предлажем да подржате и једно и друго, али да одаберете подразумевани формат.

За унос, захтеви за унос треба да се доследно именују и треба да имају смисла у контексту АПИ позива који упућујете. За излаз провјерите користите ли уобичајене распореде података. Ако закључујете излаз једног АПИ позива у а КСМЛ ознака, размислите о томе како то учинити са другим позивима.

Уобичајена је пракса да у излазне податке које пошаљете клијенту укључите неку врсту заставе статуса. Када се користи РЕСТфул АПИ приступ, то би требало бити учињено помоћу ХТТП кодова статуса. На примјер, ако сте управо обрадили ПУТ захтјев на постојећем податковном објекту, ХТТП статусни код који ћете укључити у свој одговор варираће овисно о исходу захтјева.

Уместо произвољне заставе која означава статус позива, стандардни ознака статуса "200 ОК" може се користити за означавање да је захтев успео, док се код статуса "400 лошег захтева" може означити да је захтев био неправилно обликован. Постоји доста ХТТП статусних кодова који се могу користити у различитим ситуацијама.

Користите ОАутх

Већина софтверских производа укључује неку врсту аутентификације корисника како би се приступило заштићеним ресурсима за тог корисника. Када је реч о АПИ-има, лоша пракса је да клијент прикупља корисничке акредитиве за слање на ваш сервер. Овде долази ОАутх.

ОАутх пружа бројне предности у односу на аутентификацију корисничког имена / лозинке треће стране. Поврх свега, клијент никада нема приступ корисничким подацима. Корисник се преусмерава на ваш сервер када се пријави. Након што се корисник пријави на вашу веб локацију, преусмерава се назад на клијента где ће клијент добити приступни токен који ће користити у будућим захтевима за заштићене ресурсе.

Друга важна предност коришћења ОАутх-а је корисникова могућност да у било којем тренутку откаже приступ клијенту. Ако корисник одлучи да, из било којег разлога, више не жели да клијент има приступ заштићеним ресурсима у њихово име, једноставно прелази на интерфејс који сте створили и откаже клијентов приступ.

Почните рано

Једна од најважнијих ствари које можете да постигнете успех АПИ-ја је рано покретање. Када напишете ту функцију да креирате неки унос у вашу базу података, наставите и потражите додатно време и напишите АПИ интерфејс за то.

Напишите добру документацију

Ништа не убија АПИ брже од тога што нема добру документацију. Док неки програмери могу узети лоше документовани АПИ и схватити како то треба да функционише, већина то неће желети.

Требали бисте документовати сваки АПИ позив који имате на располагању и категорисати своје АПИ позиве према врсти података на које делују. Уз документирање крајњих точака за саме позиве АПИ-ја, требало би систематски дефинисати потребне и факултативне улазне аргументе, као и структуре излазних података. Аргументи уноса требали би навести задану вриједност ако постоји, а такођер треба навести очекивани формат података, као што су број или низ. И на крају, сваки АПИ позив треба да садржи листу услова грешке и кодова статуса.

Да бисте заокружили своју документацију, обавезно додајте један или два примера за уобичајене сценарије уноса и излаза за сваки АПИ позив.

Развој АПИ-ја: Нека буде једноставно

Иако се може чинити да је развој АПИ-ја сложен подухват, идеја АПИ-ја сама по себи није нови концепт и постоји велика количина доступне документације о свакој теми коју смо овде дотакли. Само будите сигурни да користите добре праксе тамо где их можете пронаћи и да обезбедите конзистентно и добро документовано сучеље.