5 стъпки за създаване на успешен api

Това е природата на разработката на софтуер. Разработчиците създават софтуер, имайки предвид крайния потребител. Изглежда доста просто, но понякога тези потребители също са разработчици. Те не се нуждаят от разбити неща за тях. Те дори не се нуждаят от простотата. Всичко, което искат, е достъп - начин за интегриране на вашия софтуер с техния. Тук идва API (интерфейс за програмиране на приложения). Надявам се да подчертая пет стъпки, които можете да направите, за да създадете успешен API.

Напиши си домашното

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

Има много различни технологии там, но повечето API-та, които ще видите, ще използват или RESTful интерфейс, или SOAP. Ако сте на оградата кой интерфейс на API ще използвате, бих препоръчал да се подходи с RESTful подход, използвайки протокола HTTP. По-просто е от SOAP, в момента е по-популярно и ще бъде по-лесно да започнете с използването на уеб базиран софтуерен продукт.

Да бъда постоянен

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

Когато използвате RESTful подход, има много различни схеми за именуване на URI. Всеки има своите привърженици, така че просто изберете един и се придържайте към него. Същото важи и за структурата на входа и изхода. Повечето API поддържат използването на XML и JSON като входни и изходни формати. Бих предложил да подкрепите и двете, но да изберете формат по подразбиране.

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

Обичайна практика е да се включи някакъв вид флаг на състоянието в изходните данни, които изпращате обратно на клиента. Когато използвате подход RESTful API, това трябва да стане с помощта на HTTP кодове за състояние. Например, ако току-що сте обработили PUT заявка на съществуващ обект на данни, кодът на състоянието на HTTP, който включвате във вашия отговор, ще варира в зависимост от резултата от заявката.

Вместо произволен флаг, който показва състоянието на повикването, може да се използва стандартен код за състояние "200 ОК", за да се обозначи, че заявката е била успешна, докато кодът на състоянието "400 лоша заявка" може да се използва, за да означава, че заявката е била образувана неправилно. Има доста HTTP кодове за състояние, които могат да се използват в различни ситуации.

Използвайте OAuth

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

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

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

Започнете рано

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

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

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

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

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

Разработка на API: Поддържайте го просто

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