Как да тествате и играете с уеб API, лесният начин с пощальон

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

И така, как можем да използваме Postman, за да тестваме съществуващите ни API и да разберем как работят?

  • Какво е пощальон?
  • Какво ще изградим / научим?
  • Част 0: Подготовка с Пощальон
  • Част 1: Въведение в пощальона
  • Част 2: Създаване на нова заявка за пощальон за ПОЛУЧАВАНЕ на информация за Squirtle
  • Част 3: Създаване на колекция от заявки в Postman за PokéAPI
  • Част 4: Изпращане на POST заявки с Пощальон за превод на изречения, за да звучи като Йода
  • Част 5: Удостоверяване на заявки до API на Lord of the Rings с API ключ

Какво е пощальон?

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

И това не е само за тестване. Красотата е, че това може да се използва за много аспекти на работата с API за много различни членове на екипа. Може би мениджър на проекти иска да провери дали нещата работят или може да е по-лесно да направи промяна направо с API, или QA инженер трябва да се увери, че всичко продължава да работи, или разработчик иска активно да прави промени, докато работи върху самия API .

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

Какво ще изградим / научим?

Ще разгледаме два различни примерни API, за да обхванем концепциите на Postman.

Първо ще разгледаме някои прости HTTP заявки с публичен API за Pokémon.

След това ще използваме API на Yoda Translator за една част, за да демонстрираме как да правим конкретни HTTP заявки.

След като разберем как работят основите, ще използваме API на Lord of the Rings, за да научим как работи удостоверяването с API. За това ще трябва да се регистрирате за безплатен акаунт за API ключ.

Част 0: Подготовка с Пощальон

Преди да започнем, ще ви е необходим пощальон, за да следвате това ръководство. Добрата новина е, че Postman е достъпен безплатно за Mac, Windows и Linux, така че трябва да можете да намерите версия, която работи за вас.

Вземете пощальон: //www.postman.com/downloads/

Веднъж изтеглени, преминете през стандартните инструкции за инсталиране, отворете го и трябва да сме готови за работа!

Част 1: Въведение в пощальона

Първият път, когато отворите Пощальон, веднага ще ви бъде показан стартов панел с куп опции, за да започнете.

Може да изглежда малко поразително, но нека разделим някои от ключовите концепции, които ще трябва да знаем.

Искания

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

Колекции

Колекцията е група заявки. Това е удобно за организиране на вашите заявки в различни групи. Това може да бъде толкова просто, колкото два напълно различни API (т.е. Twitter срещу Slack) или може да бъде две различни групи API за един API (т.е. API на Twitter Tweets срещу API на Twitter акаунти).

Разрешение

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

Среда

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

Работни пространства

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

За целите на тази статия ще обхващаме заявки, колекции и упълномощаване.

Част 2: Създаване на нова заявка за пощальон за ПОЛУЧАВАНЕ на информация за Squirtle

Сега, когато имаме по-добро разбиране на различната терминология, нека всъщност да създадем заявка.

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

Преди да влезем в самата заявка, тя иска няколко неща.

Първото нещо, което изисква, е име. Ще започнем, като поискаме информация за Pokémon Squirtle, така че нека наречем това „Pokémon - Squirtle“.

Той също така изисква колекция, така че щракнете върху Създаване на колекция и нека наречем колекцията „Моят любим покемон“.

Щракнете върху оранжевия бутон до името на колекцията, след което натиснете Запазване .

На този етап ще имаме нова заявка, така че нека да я изградим.

Има две неща, които първо трябва да попълним за първата си заявка:

  • Тип на заявката: GET, POST, PUT и т.н. - ще използваме GET
  • URL на заявката: Крайната точка за вашата заявка за API - за нашата заявка ще използваме //pokeapi.co/api/v2/pokemon/squirtle/

И след като се уверите, че са верни, можете просто да натиснете синия бутон Изпрати вдясно и ние успешно направихме първата си заявка!

Веднага получаваме няколко неща, които можем да видим:

  • Тяло: в долната част сега трябва да видим тялото на отговора на заявката за API. За нашия Squirtle API, трябва да имаме и JSON обект с данни, като abilities, base_experienceи forms.
  • Състояние: вдясно трябва да видим кода на HTTP състоянието. „200 Ok“ е добър знак и означава, че е бил успешен!
  • Време: просто колко време е отнело заявката да завърши
  • Размер: размерът в KB (в нашия пример) на данните за отговора

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

Затова направихме първата си заявка!

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

Част 3: Създаване на колекция от заявки в Postman за PokéAPI

След като създадохме заявка, нека създадем колекция от тях. Технически вече трябваше да създадем нова колекция за Част 2, но ще създадем нова, за да научим как работят самите колекции.

В горния ляв ъгъл на потребителския интерфейс щракнете отново върху оранжевия бутон New и изберете Collection .

Подобно на заявка, той иска име, така че нека наречем това „PokéAPI“. По желание можете да добавите описание, след което щракнете върху Създаване в долната част.

Вляво сега ще видите колекцията си. Можете да изберете и разгънете папката, тъй като ще работим с нея.

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

Подобно на останалите, това иска име. Папките са нещо като колекции вътре в колекция, така че получавате подобни опции. Нека го наречем „Pokémon“ и щракнем върху оранжевия бутон Save, както преди.

Сега нека добавим нашите заявки! Първо щракнете върху трите точки до папката Pokémon, подобно на начина, по който добавихме папка към колекцията, но този път изберете Добавяне на заявка .

Нека наречем тази молба „Pokemon“. Макар да е объркващо, че имаме заявка за Pokemon вътре в папката Pokémon, Pokemon е само една от крайните точки на групата Pokémon.

Сега, нека използваме същия точен API, който използвахме с нашата заявка за Squirtle преди:

  • Тип на заявката: GET
  • URL адрес на заявката: //pokeapi.co/api/v2/pokemon/squirtle/

И подобно на преди, когато натиснем синия бутон Изпрати , трябва да видим успешна заявка!

Сега нека добавим още една заявка. Следвайте същия процес както преди, за да създадете нова заявка в папката PokéAPI Pokémon и нека наречем тази заявка „Възможности“.

Ако превъртите отговора от първата крайна точка на Squirtle, ще видите много други URL адреси на API. В горната част имаме abilitiesи имаме две различни - „порой“ и „дъждовна чиния“.

Изберете любимата си способност на Squirtle и копирайте urlстойността в новата заявка за способности, която току-що създадохме, ще използвам rain-dish.

Можем да оставим типа на заявката като GET, да натиснем синия бутон Send и отново да видим успешен отговор!

Тук получаваме много информация за нашата способност да катерица Rain Dish и някои от детайлите идват на различни езици, което е страхотно!

Така че сега имаме нова колекция PokéAPI с папка Pokémon, представляваща групата крайни точки на API на Pokémon, включително Pokemon и способности.

Ще спрем Част 3 с тези 2 заявки, но не се колебайте да продължите и да добавите колкото искате от PokéAPI заявките!

Част 4: Изпращане на POST заявки с Пощальон за превод на изречения, за да звучи като Йода

Досега сме правили само GET заявки, но какво, ако искаме да направим POST заявка, където всъщност трябва да изпратим някои данни?

За да направим POST заявка, ще използваме API на Yoda Translator от funtranslations.com. Въпреки че този API приема само един параметър, той все още е добра обществена крайна точка, която можем да използваме, за да разберем концепцията.

Първо, нека създадем нова колекция с нова заявка:

  • Колекция: Забавни преводи
  • Заявка: Йода

Този път вместо GET заявка, нашата конфигурация на заявката ще бъде:

  • Тип на заявката: POST
  • URL адрес на заявката: //api.funtranslations.com/translate/yoda

Сега този път, ако натиснем синия бутон Изпрати , ще забележим, че не получаваме успешен отговор 200, получаваме 400!

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

Точно под URL адреса на заявката щракнете върху Body . След това вместо никакъв, изберете суров като тип тяло. И накрая, най-вдясно от типовете, променете Text на JSON .

След това в пространството под него можете да добавите следното:

{ "text": "Hello, I am learning how to test APIs with Postman!" } 

А сега кликнете отново върху синия бутон Изпрати и ще получим успешен отговор!

Можем да приложим тази концепция към почти всеки API. Пощальонът не само ви позволява да публикувате JSON, но ви позволява да използвате и другите формати, които виждаме, изброени в раздела Body Type, което означава, че имате много опции в зависимост от това, което API, което използвате, изисква.

Част 5: Удостоверяване на заявки до API на Lord of the Rings с API ключ

За останалата част от инструкциите ще използваме API на Lord of the Rings.

Първо, Lord of the Rings API изисква удостоверяване, за да отправя заявки с помощта на API ключ. Така че, за да започнете, преди да се потопим, ще трябва да създадете безплатен акаунт.

//the-one-api.herokuapp.com/sign-up

След като се регистрирате и влезете, първото нещо, което ще видите, е вашият API ключ! Или копирайте този ключ надолу или запомнете къде можете да го намерите за по-късно. Ако напуснете страницата, винаги можете да я вземете, като отворите Добре дошли и след това Акаунт в навигацията на уебсайта на API.

За да започнем, нека първо създадем нова колекция и заявка:

  • Колекция: Властелинът на пръстените
  • Папка: Филм
  • Заявка: Всички филми
  • Тип на заявката: GET
  • URL адрес на заявката: //the-one-api.herokuapp.com/v1/movie

След като сте настроили горното, щракнете върху Изпрати и веднага ще забележите, че той дава отговор, който казва 401 и че не е удостоверен.

Тъй като този API изисква API ключ, точно това очаквахме. Така че нека кликнете върху раздела Упълномощаване . След това можем да изберем тип токен на приносител , а отдясно можем да поставим в нашия ключ, който току-що сме настроили с API на Lord of the Rings.

И веднага щом натиснем Изпрати , сега виждаме успешен отговор!

Това работи наистина чудесно, но какво ще стане, ако имаме куп заявки, които използват един ключ. Трябва ли да управляваме това при всяка заявка?

Вместо да го управляваме при всяка отделна заявка, ние можем да го управляваме в колекцията. Нека първо изградим друга заявка.

Създайте нова заявка в нашата колекция „Властелинът на пръстените“ и в папката „Филм“:

  • Заявка: Цитиране по филмов идентификатор
  • Тип на заявката: GET
  • URL адрес на заявката: //the-one-api.herokuapp.com/v1/movie/{id}

В тази заявка, нека използваме идентификатор от отговора на първата заявка, ще използвам, 5cd95395de30eff6ebccde5bкойто е идентификаторът на Двете кули, така че URL адресът на заявката ще изглежда така:

//the-one-api.herokuapp.com/v1/movie/5cd95395de30eff6ebccde5b

Сега, вместо да задаваме нашия маркер в оторизацията на заявката, ще оставим типа като Inherit auth от родител . Кликнете върху трите точки до колекцията и изберете Редактиране .

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

Накрая щракнете върху Актуализиране и натиснете отново синия бутон Изпрати и ще видим успешна заявка!

Вече можем да се върнем към нашата заявка за всички филми и да актуализираме упълномощаването, за да използвам тип наследяване на автентичност от родител и все пак трябва да продължи да работи!

Какво друго можем да направим с пощальона?

Въпреки че разгледах много основни неща, можете да направите много повече с Postman. Ето няколко от любимите ми.

Променливи на околната среда

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

Променливите се прилагат за много сценарии, но това е често използвано. Вижте документите на Пощальон, за да научите как.

//learning.postman.com/docs/postman/variables-and-environments/variables/

Импортиране и експортиране на колекции и данни

Страхотно нещо за пощальона е, че след като организирате заявките си, можете да ги експортирате за използване от други. Това също означава, че можете да импортирате колекции от други членове на екипа. Това прави много по-лесно да се уверите, че всички използват една и съща колекция.

Бонус: можете дори да съхранявате тези файлове в хранилище на Git, тъй като те са просто JSON.

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

//learning.postman.com/docs/postman/collections/importing-and-exporting-data/

Автоматизирано тестване

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

Въпреки че има няколко решения за това, Postman включва колектор Runner, вграден директно в приложението, а Newman е инструмент за команден ред, който ви позволява да стартирате тестове директно от терминала.

//www.postman.com/use-cases/api-testing-automation/

Кой е любимият ви начин да тествате и играете с API?

Споделете с мен в Twitter!

Последвайте ме за още Javascript, UX и други интересни неща!

  • ? Последвай ме в Туйтър
  • ? ️ Абонирайте се за моя Youtube
  • Регистрирайте се за моя бюлетин