10 важних компоненти АПИ документације

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

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

Најбољи начин да то урадите је да детаљно документујете свој АПИ. Ово укључује детаљан опис критичних компоненти како би их лакше разумели. Сазнајте неке од компоненти које бисте требали укључити у своју АПИ документацију.

Шта је АПИ документација?

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

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

Уредници попут Гоогле докумената су некада били нашироко коришћени за професионалну АПИ документацију. Данас постоје напреднији алати као што су Доцумент 360, Цонфлуенце и ГитХуб Пагес. Ови алати помажу да се интегришу текст и код за лакши радни ток.

1. Преглед и сврха АПИ-ја

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

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

Ево примера описа Аирбнб АПИ-ја:

2. Методе аутентификације и ауторизације

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

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

Документација АПИ-ја треба да води кориснике како да аутентификују и овласте своје идентитете. Следећи дијаграм приказује информације о аутентификацији Твиттер АПИ-ја.

3. Крајње тачке, УРИ обрасци и ХТТП методе

У овом одељку покажите како да приступите ресурсу. Крајње тачке показују само крај путање, па отуда и њихово име. Они показују приступ ресурсу и ХТТП методе крајња тачка ступа у интеракцију са, односно ГЕТ, ПОСТ или ДЕЛЕТЕ.

Један ресурс вероватно има различите крајње тачке. Сваки са другачијим путем и методом. Крајње тачке обично имају кратке описе своје сврхе и УРЛ образац.

Следећи пример кода приказује ГЕТ корисничку крајњу тачку на Инстаграму.

Схваташ ме? фиелдс={фиелдс}&аццесс_токен={аццесс-токен}

4. Формати захтева и одговора

Морате документовати формате захтева и одговора тако да корисник зна шта може да очекује. Захтев је УРЛ од клијента који тражи ресурс, док је одговор повратна информација са сервера.

Следи пример захтева који можете да пошаљете ЛинкедИн АПИ-ју.

ДОБИТИ https://api.linkedin.com/v2/{service}/1234

А ево примера одговора који може да врати:

{
 "ид": 1234,
 "релатедЕнтити": "урн: ли: релатедЕнтити: 6789"
}

5. Параметри и заглавља

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

Постоје различити типови параметара, укључујући параметре заглавља, путање и стринга упита. Крајње тачке могу да садрже различите типове параметара.

Можете укључити неке параметре као заглавља ХТТП захтева. Обично су то за потребе аутентификације, као што је АПИ кључ. Ево примера заглавља са АПИ кључевима:

заглавља: ​​{
 'Кс-РапидАПИ-Кеи': 'фд40ада866мсх4д8б69е4аа2дд19п12е47фјсн7ефдцбц75635',
 'Кс-РапидАПИ-Хост': 'вфт-гео-дб.п.рапидапи.цом'
}

Параметре путање укључујете у тело крајње тачке директно на УРЛ. Они показују кориснику како и где да постави параметре и како ће се појавити одговор. Речи у витичастим заградама су параметри.

Такође можете користити двотачке или другу синтаксу за представљање параметара путање.

/service/myresource/user/{user}/bicycles/{bicycleId}

Са параметрима упита, морате да поставите знак питања (?) пре упита на крајњој тачки. Одвојите сваки параметар након тога амперсандом (&). Мицрософт има добру документацију о Грапх АПИ-ју.

6. Кодови грешака и руковање грешкама

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

ЛинкедИн обезбеђује стандардне ХТТП кодове грешака за руковање грешкама:

7. Пример исечака кода

Исечци кода су суштински делови ваше документације. Они показују корисницима како да интегришу АПИ у различитим језицима и форматима. Укључите како да инсталирате и интегришете СДК (комплет за развој софтвера) на различитим језицима у документацију.

РапидАПИ има добре примере исечака кода за програмере:

9. АПИ верзија верзија и евиденције промена

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

Корисници могу да наставе да користе старије верзије или да пређу на напредне на време. Ако постоје нове промене у евиденцији, укључите их у документацију како би корисници били свесни.

Мицрософт Грапх АПИ има добро документоване евиденције промена:

На крају, у документацију укључите важне контакте за подршку и повратне информације. Ово обезбеђује да корисници могу да вас контактирају са извештајима о грешкама и информацијама о томе како да побољшају АПИ.

Вредност АПИ документације

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

Документација оживљава АПИ. Детаљно објашњава компоненте једноставним језиком који корисницима продаје своју вредност и употребу. Корисници ће радо конзумирати ваш АПИ ако имају сјајно искуство програмера.

Добра документација такође помаже да се поједностави одржавање и скалирање АПИ-ја. Тимови који раде са АПИ-јем могу да користе документацију за управљање њиме.