API е толкова добър, колкото и неговата документация, така че се уверете, че вашият е откриваем с висококачествени инструкции и други важни подробности.

Все повече организации използват силата на API, за да оптимизират бизнеса си. API се превърнаха в начин за отключване на стойност и предоставяне на допълнителна услуга.

Въпреки общата им популярност, не всеки API е успешен. Приемането и използването на API до голяма степен определя неговия успех. За да увеличите приемането, вашият API трябва да бъде лесен за намиране и използване.

Най-добрият начин да направите това е като документирате подробно своя API. Това включва детайлизиране на критичните компоненти, за да ги направи по-лесни за разбиране. Открийте някои от компонентите, които трябва да включите във вашата документация за API.

Какво е API документация?

API документацията е техническо съдържание, което описва API в детайли. Това е ръководство, съдържащо цялата информация, необходима за работа с API. Документът обхваща жизнения цикъл на API и инструкции за интегриране и използване на неговите компоненти.

instagram viewer

API документацията обхваща описания на ресурси, крайни точки, методи, заявки и примери за отговори. Може също така да включва практически ръководства и уроци, показващи на потребителите как да го интегрират. Проучването на всеки раздел дава на потребителите солидно разбиране за интегрирането и използването на API.

Редактори като Google Docs някога са били широко използвани за професионална API документация. В днешно време има по-усъвършенствани инструменти като Document 360, Confluence и GitHub Pages. Тези инструменти помагат за интегрирането на текст и код за по-лесни работни процеси.

1. Преглед и цел на API

Първата стъпка в документирането на API е да информирате потребителите за какво става въпрос. Включете информация за вида ресурси, които предоставя. API обикновено имат различни ресурси, които връщат, така че потребителят може да поиска това, от което се нуждае.

Описанието е кратко, обикновено едно до три изречения, които описват ресурса. Опишете наличния ресурс, крайните точки и методите, прикрепени към всяка крайна точка. Като разработчик на API, вие най-добре опишете неговите компоненти, функционалност и случай на използване.

Ето пример за описание на API на Airbnb:

2. Методи за удостоверяване и оторизация

API обработват хиляди заявки и огромни количества данни. Удостоверяването е един от начините да гарантирате, че данните на вашия API и потребителите са защитени от хакери. API автентификацията проверява самоличността на потребителя и им дава достъп до ресурси.

Има няколко начина за осигуряване сигурност на крайната точка. Повечето API използват API ключ. Това е низ от знаци, които потребителят може да генерира от уебсайта и да използва за удостоверяване.

Документацията на API трябва да насочва потребителите как да удостоверяват и упълномощават своята самоличност. Следната диаграма показва информация за удостоверяване на API на Twitter.

3. Крайни точки, URI модели и HTTP методи

В този раздел покажете как да получите достъп до ресурса. Крайните точки показват само края на пътя, откъдето идва и името им. Те показват достъп до ресурса и HTTP методи крайната точка взаимодейства с, а именно GET, POST или DELETE.

Един ресурс вероятно има различни крайни точки. Всеки с различен път и метод. Крайните точки обикновено имат кратки описания на тяхната цел и URL модел.

Следният примерен код показва потребителска крайна точка GET в Instagram.

Хвани ме? fields={fields}&access_token={access-token}

4. Формати на заявка и отговор

Трябва да документирате форматите на заявката и отговора, така че потребителят да знае какво да очаква. Заявката е URL от клиент, който иска ресурс, докато отговорът е обратна връзка от сървъра.

Следното е примерна заявка, която можете да изпратите до API на LinkedIn.

ВЗЕМЕТЕ https://api.linkedin.com/v2/{service}/1234

И ето примерен отговор, който може да върне:

{
 "id": 1234,
 "relatedEntity": "урна: li: relatedEntity: 6789"
}

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

Трябва също така да документирате параметрите на вашите крайни точки, които са опции, които можете да им предадете. Параметрите могат да бъдат идентификатор или номер, който указва количеството или вида на данните, върнати в отговор.

Има различни типове параметри, включително параметри на заглавка, път и низ на заявка. Крайните точки могат да съдържат различни типове параметри.

Можете да включите някои параметри като заглавки на HTTP заявка. Обикновено те са за целите на удостоверяване като API ключ. Ето пример за заглавка с API ключове:

заглавки: {
 „X-RapidAPI-Key“: „fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635“,
 „X-RapidAPI-Host“: „wft-geo-db.p.rapidapi.com“
}

Включвате параметри на пътя в тялото на крайната точка точно върху URL адреса. Те показват на потребителя как и къде да постави параметрите и как ще се появи отговорът. Думите във фигурни скоби са параметри.

Можете също да използвате двоеточия или друг синтаксис, за да представите параметрите на пътя.

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

При параметрите на заявката трябва да поставите въпросителен знак (?) преди заявката в крайна точка. Разделете всеки параметър след това с амперсанд (&). Microsoft има добра документация за Graph API.

6. Кодове за грешки и обработка на грешки

Понякога HTTP заявките са неуспешни, което може да остави потребителя объркан. Включете очакваните кодове за грешки в документацията, за да помогнете на потребителите да разберат грешките.

LinkedIn предоставя стандартни HTTP кодове за грешка за обработка на грешки:

7. Примерни кодови фрагменти

Кодовите фрагменти са съществени части от вашата документация. Те показват на потребителите как да интегрират API на различни езици и формати. Включете в документацията как да инсталирате и интегрирате SDK (комплекти за разработка на софтуер) на различни езици.

RapidAPI има добри примери за кодови фрагменти за разработчици:

9. API версии и регистрационни файлове за промени

API версиите са съществена част от API дизайн. Той гарантира предоставянето на услуги без прекъсване на вашите потребители. Версионирането може да подобри API с нови версии, без да засяга клиентските приложения.

Потребителите могат да продължат да използват по-стари версии или да мигрират към напреднали във времето. Ако има нови промени в регистрационните файлове, включете ги в документацията, така че потребителите да са наясно.

Microsoft Graph API има добре документирани журнали за промени:

И накрая, включете важни контакти в документацията за поддръжка и обратна връзка. Те гарантират, че потребителите могат да се свържат с вас с доклади за грешки и информация как да подобрят API.

Стойността на API документацията

Ако създадете API за търговска стойност, потреблението определя неговия успех. И за да могат потребителите да използват вашия API, те трябва да го разбират.

Документацията вдъхва живот на API. Той обяснява подробно компонентите на прост език, който продава своята стойност и употреба на потребителите. Потребителите с удоволствие ще консумират вашия API, ако имат страхотно изживяване на разработчиците.

Добрата документация също помага за опростяване на поддръжката и мащабирането на API. Екипите, работещи с API, могат да използват документация, за да го управляват.