Винаги сте се чудили 'Какво си мислеха?' при интегриране на уеб услуга чрез нейния API? В противен случай сте имали по-голям късмет от мен.
Всеки разработчик на софтуер знае колко лесно е да оставите даден проект да се превърне в код за спагети, а уеб API не по-малко са склонни да водят до заплетена мрежа. Но не е необходимо да е така. Всъщност е възможно да се проектира страхотен уеб API, които хората всъщност ще направят наслади се използване, и че ще ви хареса и да създавате. Но как? Отговорът на този въпрос е за какво става въпрос в този пост.
През повечето време, когато създавате решения, проектирате за крайни потребители, които не са програмисти или които обикновено не са технически сложни. Давате им графичен интерфейс и ако сте си свършили работата правилно, сте получили доста добра идея от тях за това, което им е необходим, за да направи интерфейсът.
Но Разработка на API е различен. Вие проектирате интерфейс за програмисти , вероятно дори без да знаят кои са те. И каквито и да са те, те ще имат техническата сложност (или поне ще си помислят, че имат техническа сложност), за да посочат всеки малък недостатък във вашия софтуер. Потребителите ви вероятно ще бъдат толкова критични към вашия API, колкото и вие към техните, и ще се радват да го критикуват напълно.
И в това се крие част от иронията, между другото. Ако някой трябва да разбере как да се направи уеб API, който е лесен за използване, това е Вие . В крайна сметка вие сте софтуерен инженер точно като потребителите на вашия API, така че споделяте тяхната перспектива. Нали?
Е, докато със сигурност разберете тяхната перспектива, не е задължително дял тяхната перспектива. Когато се развивате или подобрявате Вашият API, вие имате перспективата на API дизайнер като имат предвид перспективата на API потребител .
API дизайнери обикновено се фокусират върху въпроси като „Какво трябва да направи тази услуга?“ или „Какво трябва да предостави тази услуга?“ , докато Потребители на API са фокусирани върху „Как мога да използвам този API, за да правя това, от което се нуждая?“ или по-точно, „Как мога да похарча минимум усилията, за да извлека това, от което се нуждая, от този API?“ .
Тези различни въпроси водят до две изключително различни перспективи. В резултат на това необходимата предпоставка за проектиране на a страхотен API е да измести вашата гледна точка от тази на дизайнера на API към тази на потребителя на API. С други думи, непрекъснато си задавайте въпросите, които естествено бихте задали, ако сте вашият потребител. Вместо да мислите какъв е вашият API мога направете, помислете за различните начини, от които може да се нуждае или иска да бъде използвани и след това се съсредоточете върху максимално улесняване на тези задачи за потребителите на вашия API.
Въпреки че това може да звучи лесно и очевидно, поразително е колко рядко изглежда, че API са проектирани по този начин. Помислете за API, които сте срещали в кариерата си. Колко често изглежда, че са проектирани с тази перспектива? Дизайнът на уеб API може да бъде предизвикателство.
Така че с това казано, нека да продължим и да поговорим за 5 Златни правила за проектиране на страхотен уеб API , а именно:
Документация. Да, започвам от тук.
Мразите ли документацията? Е, мога да съчувствам, но сложете шапката си „потребителска перспектива“ и ще се обзаложа, че единственото нещо, което мразите повече от това да пишете документация, е да се опитате да използвате API без документи. Доказах гледната си точка.
Изводът е, че ако искате някой да използва вашия API, документацията е от съществено значение. Просто трябва да разберете това правилно. Това е първото нещо, което потребителите ще видят, така че в някои отношения това е като опаковката за подаръци. Представете се добре и хората са по-склонни да използват вашия API и да се примиряват с всякакви идиосинкразии.
И така, как да напишем добра документация?
Сравнително лесната част е документирането на самите методи на API; т.е. примерни заявки и отговори, заедно с описания на всеки от елементите и в двата. За щастие има все по-голям брой софтуерни инструменти, които улесняват и опростяват задачата за генериране на документация. Или можете сами да напишете нещо, което интроспектира вашия API, крайни точки и функции и генерира съответната документация за вас.
данък за корекция на границите спрямо тарифа
Но това, което разделя страхотната документация от адекватната, е включването на примери за употреба и в идеалния случай уроци. Това е, което помага на потребителя да разбере вашия API и къде да започне. Той ги ориентира и им помага да заредят вашия API в мозъка си.
Например, ако разработчиците на Twilio трябва да изброят всеки клас, всеки метод и всеки възможен отговор на техния API, но не са си направили труда да споменат, че можете да изпратите SMS, да проследите обаждане или да купите телефонен номер чрез техния API, това ще отнеме наистина дълго време потребителят на API да намери тази информация и да я разбере сплотено. Можете ли да си представите да сортирате гигантско дърво от класове и методи, без да имате представа за какво са били използвани, освен името им? Звучи ужасно нали? Но точно това правят толкова много доставчици на API, като по този начин оставят своите API непрозрачни за никого, освен за тях самите. The Rackspace CloudFiles разработчик и ръководство за API е един такъв пример; трудно е да се ориентирате, освен ако вече не разбирате какво правят и какво предоставят.
Затова напишете кратки уроци, които помагат на разработчика да започне да работи бързо, с поне скелет на това, което се опитват да направят, и след това ги насочете към по-подробния, напълно документиран списък с функционалности, за да могат да се разширят върху това, което имат.
След като приключите с вашата документация, не забравяйте да потвърдите, че има смисъл за хора, различни от вас самите. Изпратете го на други разработчици във вашата мрежа, не им давайте никакви инструкции, освен да ги насочвате към документацията, и ги помолете да следват урок или да създадат нещо наистина основно за около 15 минути. Ако те не могат да имат основна интеграция с вашия API за 15 минути, имате още работа.
За някои забележителни примери за отлична и подробна документация вижте Twilio , Джанго , и MailChimp . Нито един от тези продукти не е непременно най-добрият на своите пазари (въпреки че всички те са добри продукти), но въпреки това те се отличават, като предоставят едни от най-добрите документи на своите пазари, което със сигурност е улеснило широкото им приемане и пазарен дял.
Ако някога сте използвали API на Facebook , знаете колко често те отхвърлят и напълно пренаписват своите API. Без значение колко уважавате тяхната хакерска култура или техния продукт, тяхната перспектива не е подходяща за разработчици. Причината да продължават да са успешни е, че имат милиард потребители, а не защото техният API е страхотен.
Но вероятно нямате лукса на такава мамутна потребителска база и пазарен дял, така че ще ви е необходим много по-малко нестабилен API, поддържащ старите версии работещи и поддържани за доста дълъг период от време. Може би дори години. Така че към този край, ето няколко съвета и трикове.
Да кажем например, че вашият API е достъпен чрез URL | | + + _ | и предоставя своя отговор във формат JSON. Макар че на пръв поглед това може да изглежда добре, какво се случва, когато трябва да промените формата на отговора на JSON? Всички, които вече са интегрирани с вас, ще се счупят. Ами сега.
Така че направете малко планиране напред и версирайте своя API от самото начало, като изрично включите номер на версия в URL адреса (например http://myapisite.com/api/widgets или http://myapisite.com/api/widgets?version=1), така че хората да могат да разчитат на версия 1, която работи и да могат да надстроят до всяка следваща версия, когато са готови да го направят. Ако в даден момент трябва да премахнете предишна версия, продължете, но дайте достатъчно известие и предложите някакъв план за преход.
Добрата схема за URL ще включва основни версии в URL. Всяка промяна в изходния формат или поддържаните типове данни трябва да доведе до наблъскване до нова основна версия. Като цяло е приемливо да запазите същата версия, ако всичко, което правите, е да добавяте ключове или възли към изхода си, но за да сте в безопасност, всеки път, когато изходът се промени, извадете версия.
Освен че са стабилни във времето, API трябва да бъдат вътрешно последователни. Виждал съм много приложни програмни интерфейси (API), които променят имената на параметрите или методите за публикуване на данни, в зависимост от използваната крайна точка. Вместо това, трябва да обработвате общи параметри в глобален план във вашия API и да използвате наследство или споделена архитектура, за да използвате повторно едни и същи конвенции за именуване и обработка на данни последователно във вашия API.
И накрая, трябва да запишете и публикувате дневник на промените, за да покажете разликите между версиите на вашия API, така че потребителите да знаят как точно да надстроят.
Свързани: Урок за гроздови скъпоценни камъни: Как да изградите REST-подобен API в RubyБоклук вътре, боклук навън (GIGO) е добре позната мантра за повечето програмисти. Приложен към дизайна на уеб API, този ръководен принцип има тенденция да диктува доста строг подход за заявяване на валидиране. Звучи страхотно, нали? Няма бъркотия, няма проблем.
И все пак, както при всичко, трябва да има някакъв баланс. Тъй като не е възможно да се предвиди всеки начин, по който потребителите ще искат да използват вашата услуга, и тъй като не всяка клиентска платформа е последователна (т.е. не всяка платформа има много добра JSON поддръжка, прилична OAuth библиотека и т.н.), добре е да имате поне някаква степен на гъвкавост или толерантност по отношение на вашите входни и изходни ограничения.
Например, много API ще поддържат различни изходни формати, като JSON, YAML, XML и др. ал., но ще поддържа само посочване на формата в самия URL адрес. В духа на запазване на гъвкавостта, можете да позволите това също да бъде посочено в URL адреса (напр. http://myapisite.com/api/widgets/v1) Или да прочетете и разпознаете /api/v1/widgets.json HTTP заглавка или поддържа променлива на низ за заявка като Accept: application/json и т.н.
И докато сме готови, защо да не позволим посоченият формат да не се отчита с малки и малки букви, така че потребителят да може да посочи ?format=JSON също така? Това е класически пример за начин за облекчаване на ненужните смущения за потребителя на вашия API.
Друг пример е разрешаването на различни начини за въвеждане на променливи. Така че, точно както имате различни изходни формати, позволете и различни входни формати (напр. Обикновени POST променливи, JSON, XML и др.). Трябва поне да поддържате стандартни POST променливи, а много съвременни приложения също поддържат JSON, така че тези две са добро място за начало.
Въпросът тук е, че не трябва да приемате, че всички споделят техническите ви предпочитания. С малко проучване на това как работят други API и чрез диалог с други разработчици, можете да съберете други полезни алтернативи и да ги включите във вашия API.
Очевидно сигурността е едно от най-важните неща, които да се вгради във вашата уеб услуга, но толкова много разработчици я правят абсурдно трудна за използване. Като доставчик на API, вие трябва да предлагате използваеми примери за това как да удостоверите и упълномощите при достъп до вашия API. Това не би трябвало да е труден проблем, върху който крайният потребител прекарва часове, работейки. Поставете си за цел, че или не трябва да пишат код, или им отнема по-малко от 5 минути, за да го напишат.
За повечето API аз предпочитам прост базирана на токени удостоверяване , където токенът е произволен хеш, присвоен на потребителя и той може да го нулира по всяко време, ако е бил откраднат. Позволете на маркера да се предава през POST или HTTP заглавка. Например потребителят може (и трябва) да изпрати Токен SHA-1 като POST променлива или като заглавка във формат като „Оторизация: da39a3ee5e6b4b0d3255bfef95601890afd80709“.
Освен това изберете защитен маркер, а не кратък цифров идентификатор. Нещо необратимо е най-добре. Например относително лесно е просто да генерирате SHA токен по време на създаването на потребителя и да го съхраните в базата данни. След това можете просто да поискате вашата база данни за всички потребители, които съответстват на този маркер. Можете също така да направите знак, генериран с уникален идентификатор и стойност на солта, нещо като ?format=json, и след това да направите заявка за всеки потребител, който съответства; напр. SHA(User.ID + 'abcd123').
Друг много добър вариант е OAuth 2 + SSL . Така или иначе би трябвало да използвате SSL, но OAuth 2 е сравнително лесен за внедряване от страна на сървъра и библиотеките са налични за много често срещани програмни езици.
Ако API, който сте създали, трябва да бъде достъпен на публичен уебсайт чрез JavaScript, трябва също така да сте сигурни, че сте проверили списък с URL адреси на акаунт за маркера. По този начин никой не може да отиде да проверява повикванията към вашия API, да открадне маркера от вашия потребител и да го използва за себе си.
Ето някои други важни неща, които трябва да имате предвид:
Функционалност на белия списък. API обикновено ви позволяват да извършвате основни операции по създаване, четене, актуализиране и изтриване на данни. Но не искате да разрешавате тези операции за всеки обект, затова се уверете, че всеки има бял списък с допустими действия. Уверете се например, че само оторизирани потребители могат да изпълняват команди като where TokenFromPost = SHA(User.ID + 'abcd123'). По същия начин всички полезни заглавки, изпратени в заявката на потребителя, също трябва да бъдат валидирани спрямо белия списък. Ако разрешавате заглавки от тип Content, проверете дали каквото и да изпраща потребителят, действително съвпада с списък с поддържани типове съдържание. Ако не стане, изпратете обратно съобщение за грешка като отговор 406 Not Acceptable. Белият списък е важен, тъй като много API се генерират автоматично или вместо това се използва черен списък, което означава, че трябва да бъдете изрични относно това, което не искам. Златното правило на сигурността обаче е да започнете с абсолютно нищо и само изрично да позволите това, което вие направете искам.
разработване, управлявано от тестове, срещу развитие, ориентирано към поведението
Защитете се срещу Подправяне на заявки между сайтове (CSRF) . Ако разрешавате удостоверяване на сесия или бисквитка, трябва да сте сигурни, че се предпазвате от CSRF атаки. The Проект за отворена защита на уеб приложения (OWASP) предоставя полезни насоки за начини за предотвратяване на тези уязвимости .
Проверка на достъпа до ресурси. Във всяка заявка трябва да проверите дали на потребителя всъщност е разрешен достъп до конкретния елемент, към който се позовава. Така че, ако имате крайна точка за преглед на данните на кредитната карта на потребител (напр. /user/delete/), Уверете се, че идентификаторът „152423“ препраща към ресурс, до който потребителят наистина има право да получи достъп.
Проверете всички въведени данни. Цялото въвеждане от потребител трябва да бъде сигурно анализирано, за предпочитане с помощта на добре позната библиотека, ако използвате сложен вход като XML или JSON. Не изграждайте свой собствен синтактичен анализатор, или ви очаква свят на нараняване.
Това наистина е най-важното правило в групата и се основава на всички останали. Както споменах по време на правилото за документация, изпробвайте това с хора, които са нови за вашия API. Уверете се, че те могат да стартират и работят с най-малкото основно изпълнение на вашия API, дори ако то е просто следване на урок, в рамките на няколко минути. Мисля, че 15 минути са добър гол.
Ето някои конкретни препоръки за улесняване и улесняване на приемането на вашия API:
Уверете се, че хората действително могат да използват вашия API и че той работи за първи път, всеки път. Нека нови хора се опитват да внедрят API от време на време, за да проверят дали това не е объркващо по някакъв начин, срещу което сте станали имунизирани.
Не го усложнявай. Не правете никакво изискано удостоверяване. Не правете някаква луда персонализирана схема за URL адреси. Не преоткривайте SOAP, JSON, REST или нещо друго. Използвайте всички инструменти, които можете, които вече са внедрени и са широко приети, така че разработчиците трябва да научат само вашия API, а не вашия API + 10 неясни нови технологии.
Осигурете специфични за езика библиотеки за взаимодействие с вашата услуга. Има някои приятни инструменти за автоматично генериране на библиотека за вас, като Алпака или Apache Thrift . В момента Alpaca поддържа Node, PHP, Python и Ruby. Thrift поддържа C ++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C #, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi и др.
Опростете всяка необходима регистрация. Ако не разработвате API с отворен код или ако има някакъв процес на регистрация, уверете се, че при регистрация потребителят е много бързо насочен към урок. И направете процеса на регистрация напълно автоматизиран, без да е необходимо човешко взаимодействие от ваша страна.
Осигурете отлична подкрепа. Голяма бариера пред осиновяването е липсата на подкрепа. Как ще се справите и отговорите на доклад за грешка? Какво ще кажете за неясна документация? Неопитен потребител? Форумите, инструментите за проследяване на грешки и поддръжката по имейл са фантастични стартове, но се уверете, че когато някой публикува грешка, вие наистина я адресирате. Никой не иска да види форум на призраци или гигантски списък с грешки, които не са били адресирани.
Уеб услугите и техните API са в изобилие. За съжаление, по-голямата част е трудна за използване. Причините варират от лош дизайн, до липса на документация, до нестабилност, до нерешени грешки или, в някои случаи, всичко по-горе.
Следването на указанията в тази публикация ще ви помогне да гарантирате, че вашият уеб API е чист, добре документиран и лесен за използване. Такива API са наистина редки и поради това са много по-склонни да бъдат широко възприети и използвани.
Свързани: Урок за обратното проектиране на частния API на вашия софтуер: Хакване на вашия диван
