Ова е гостински текст на Марјан Николовски од Emit Knowledge. Марјан е ко-основач Team lead Full stack .NET и Javascript инженер, говорник и опен сорс контрибутор. Текстот е првично објавен на блогот на Emit Knowledge.

---

Понекогаш ќе имате можност да го решите предизвикот на пишување и одржување на техничка документација за вашиот продукт REST API. Креирањето на API е лесно, нели? Технички, да лесно е. Најголемиот предизвик е кога некој треба за првпат да го користи вашето API. Тогаш сфаќате дека никој, освен развојниот тим што се случува зад сцените. За да го избегнете овој проблем, би сакал да го споделам нашето искуство со API-то за праќање на фактури – Envoice.

Планирање

Компаниите денес имаат комплексни бизнис процеси кои се распространуваат низ различни софтверски системи. Денес најкористени софтверски системи не се оние кои нудат повеќе функционалности, туку оние кои нудат API и можност за интеграција со други популарни сервиси. Имајќи го ова в предвид, ако го планирате вашиот следен потфат или веќе развивате продукт ќе треба да одвоите време за да им овозможите на корисниците да го интегрираат вашиот сервис во нивниот екосистем. Постојат неколку аспекти што треба да ги разгледате кога се подготвувате за развој на API:

• Какви активности ќе дозволите преку API?
• Какви податоци се споделуваат?
• Како ќе се пристапува до API и од кој може да пристапи (безбедност, автентикација и овластување)?
• Ограничување на барањата за API AKA – граници на стапки;
• Избор на соодветна стратегија за верзијата за компатибилност;
• Алатки за документирање и одржување на документацијата за API;
• Примери за управување и одржување на интеграцијата;

Тука ќе ги разгледаме следните аспекти:

• Какви активности ќе дозволите преку API?
• Какви податоци се споделуваат?
• Како ќе се пристапува до API и од кој може да пристапи (безбедност, автентикација и овластување)?
• Алатки за документирање и одржување на документацијата за API;
• Примери за управување и одржување на интеграцијата;

Да почнеме:

Пишување на API интерфејс

Со оглед на тоа дека веќе го читате овој пост претпоставувам дека сте креирале Web API 2.0 контролер како примерот подолу:

Имаме крајна точка која ги опишува процесите поврзани со „клиент“ домен ентитетите. Решаваме дека сакаме да им овозможиме на девелоперите ова да го прават програмски со:

• Листа на сите клиенти поврзани со авторизираниот акаунт;
• Креирање нов клиент;
• Ажурирање на постоечки клиент;
• Бришење на постоечки клиент;
• Проверка дали постоечки клиент може да биде избришан;
• Враќање на деталите за побараниот клиент.

Какви акции ќе дозволиме преку API

Најпрво потребно е да одлучиме какви податоци ќе бидат процесурани и ќе се враќаат кон корисникот. На пример, клиент за мапирање на детали за клиент повикува Client API:

Безбеден интерфејс

Освен поставувањето на RequireSSL атрибут, потребно е да обезбедиме дека може да го идентификуваме повикувачот на API. Пример, потребен ни е безбеден процес за креирање на нов клиент.

Едноставен и ефикасен пристап е да користиме „API Auth Key“ и „API Auth Secret“. Со RNGCryptoServiceProvider може да креираме Auth Key и Secret и да ги „врземе“ на корисникот. Мора да се обезбеди да може да се регенерираат. Забелешка: Препорачана должина на клуч е 128 и за Auth Key и за Secret. За да можеме да го автентицираме повикот потребна е имплементација на Application_AuthenticationRequest методот во Global.asax.cs.

Сите повици за кои е потребна автентикација мора да содржат Auth Key и Secret header.

Ако Auth Key и Secret се валидни, ќе дозволиме барањето да се изврши. Оваа проверка може да се постигне со кастомизиран атрибут за авторизација.

Алатки за документирање и одржување на API документација

Во моментов има огромна заедница и поддршка за Swagger – framework за развој на API за Open API Specification. За наша среќа го поддржува .NET екосистемот преку NuGet package: Swashbuckle. Со инсталација на овој пакет ќе добиете поддршка за Swagger 2.0. По инсталацијата ќе пронајдете нов Swagger конфигурациски фајл под App_Start\SwaggerConfig.cs.

Конфигурација овозможува екстензивни промени и може да менувате за тоа како се генерираат спецификациите за вашето API. Штом ќе завршите може да го проверите резултатот за претходно дефинираната насока за креирање на документација. Прикажаната API спецификација ќе ги содржи сите прикажани API методи заедно со коментарите и DTO. Коментарите ќе се читаат од XML коментарите од излезниот директориум. вообичаено Project.Namespace.XML.

Конфигурација на екстензија

Со оглед на тоа дека потребите може да се менуваат најверојатно ќе ви биде потребна функционалност која не доаѓа со основите. Добра вест е дека може самите да си напишете екстензија и да го препишете процесот на креирање на API спецификација. Во случај да ви е потребно да промените нешто, може да ги напишете следните екстензии:

• Operation filters – препишување на спецификациите за операциското ницо пример креирање на нова акција за клиент;
• Schema filters – препишување на специфична the specification „schema“. Пример исклучување на некое проперти од „request/response“;
• Document filters – препишување на документот. Највисоко во хиерархијата. „Пример  Set all operations to lowercase“;

Има уште куп корисни примери кои може да ги пронајдете на Swashbuckle за Document, Schema и Operation филтри. Сигурно проверете ги пред да започнете да правите некој самите.

Генерирање на UI/UX за API

Девелоперите не секогаш се радуваат на можноста за креирање на UI/UX, сепак неопходно е за креирање на добра API документација. Swashbuckle нуди UI со самото користење. За жал, не е добро дизајнирано и собира необработени податоци од спецификациите. Сепак една библиотека ќе помогне: REDOC. Redoc ви помага да генерирате модерен UI со едноставно додавање на URL до API спецификацијата.

Би требало да го добиете овој резултат:

Ако документацијата не е доволна

Често по издавањето на API ќе сфатите дека развивачи го интегрираат вашето апи во некој постоечки продукт и имаат потреба од сфатат што вашето API прави и како може да го искористат со својот програмски јазик. Ова најверојатно ќе ја намали продуктивноста на вашиот тим, ќе поминете часови објаснувајќи како да се користи API-то со NET, PHP, Go, Ruby, Python… За да го намалите времето кое го минувате во поддршка, има неколку чекори кои може да и преземете претходно.

• Креирање на Postman колекција
• Креирање на cURL примери на GitHub
• Сместување на Postman колекции и GitHub примери во документацијата
• Postman ви овозможува да креирате околина од која секој кој е заинтересиран да го користи API-то може да го користи за да извршува барања, да ги истражува можностите на API-то и да експортира примери во нивниот омилен програмски јазик.

Ова ќе ви овозможи да заштедите на време потребно за пишување и одржување на клиент библиотеки во различни програмски јазици и ќе го олесни учењето на овие специјализирано библиотеки.

Заклучок

Како што го развивате API-то не заборавајте дека документацијата ќе биде автоматски апдејтирана, но сепак ќе треба да ги надградите Postman и GitHub примерите. Додека развивате верзии, одделете време кое ќе биде потребно за одржување на документација и анализа за да не ја уништите постоечката интеграција кај клиентите.