Безболезнено въведение в работата с API

Типично API обаждане

Ако работите навсякъде в близост до индустрията за уеб разработки, със сигурност ще чуете тези три скандални букви: A. P. I.

Те се хвърлят наоколо както от начинаещи, така и от експерти:

„Защо трябва да направя повикване в API? Има ли номер? “

„Просто обаждане до този API на трети страни ще свърши работа.“

„Ще ви създадем RESTful API; като се уверите, че новата ви система играе добре с други услуги. “

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

Защо? Е, научаването да използвате правилно API-ите може да опрости, ускори и засили работния процес на вашата разработка. Изграждането или интегрирането на API носи ползи както за клиентите, така и за вас самите.

Като разработчици често чувате съвета: „не измисляйте отново колелото“.

Вицове настрана, API-ите играят съществена роля, за да не измислите отново колелото. Разбирането на основите на APIs е изключително важно умение за съвременните уеб разработчици. В тази публикация ще ви помогна да направите точно това. Ще покрием:

  • Ползите от използването на API
  • Какво всъщност представлява API
  • Какви видове API има
  • Случаи за практическо използване

Нека се потопим в него, нали?

Защо да използвате API?

Изравнете уменията си за разработка с API

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

Преди да навлезете в дебелозърнестия, позволете първо да ви убедя, че разбирането на API-тата си струва да отделите време. Как така?

Тъй като научаването да използвате API значително увеличава ефективността на вашето развитие.

Първо, тя ви позволява да използвате предишна логика, която не е нужно да пишете. Някои неща, които може просто да не можете да кодирате сами! За да спестите ценно време като програмист, е важно да имате представа как изглежда пейзажът на API.

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

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

Какво точно представляват API-тата?

Web API, изображение от MS

Официалното (плашещо) определение става така:

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

Малко тежко, а? Нека да свалим академичната проза до голяма степен. Ето една по-приятелска, приготвена в домашни условия дефиниция на API:

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

За да хвърлим още по-добра светлина върху API-тата, нека да изброим какви НЕ са:

  • API не е непременно външна услуга. Например, можете да включите библиотеки директно във вашето решение ИЛИ да ги използвате чрез API.
  • API не е само интерфейс. Това е както спецификация / формат, така и изпълнение.
  • API не е GUI (графичен потребителски интерфейс). API не прави взаимодействие на графично ниво. Той работи единствено върху програмния слой. Това може да бъде или чрез език за програмиране, или чрез комуникационен протокол.

Различни видове API

Всички API не са създадени равни.

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

Имайте предвид, че хората имат наистина различни подходи към изграждането на API. Ако тази тема ви интересува, Google около „API модели на проектиране“ и „API парадигми“. Или просто започнете с тази кокетна статия за начално ниво. :)

Endpoints

Целта на APIs е да улеснят живота ви като програмист. Как правят това?

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

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

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

Ключовият момент тук е, че основната логика на тези функции е изцяло абстрахирана. Нямате нужда от знания за това какво се случва вътре в тях, за да ги използвате.

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

Долният ред е следният: API е точно като всеки интерфейс.

Като сравнение, светлинен превключвател ще включи светлина, независимо дали знаете как работят електрическите токове или не. (Като млад възраст също научих, че трябва да платите сметката за ток, за да работи тя ... но това е различна история ...)

Как да използвате API: практически примери

Нека сега разкажем теорията за лесна практика.

Четене на документация за API

Не искам прекалено много да разширявам концептуалните обяснения. Вместо това, нека анализираме наистина прям API. Ще видим как работи при сценарий в реалния живот. За целта ще използваме родния обект на JavaScript Math. Можете да прочетете документацията му тук.

Документите обясняват как всяка функция на Math обекта описва какъв трябва да бъде входният формат. Например, това може да бъде число или масив от числа.

Документите описват и формата на изхода.

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

Например, ако запалите конзолата на браузъра си и напишете Math.sqrt (без да изпълнявате функцията), ще видите нещо като:

ƒ sqrt () {[родния код]}

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

Основни примери за случаи на използване на API

Има много неща, които могат да се направят с популярни доставчици на API.

API на Google Maps често се използва за изграждане на по-добро потребителско изживяване с данни, базирани на картографиране в реално време и сигнали за трафик. API на Twitter може да се използва за филтриране и показване на насочени туитове в реално време.

Подозирам, че много от вас се интересуват повече от уеб-базирани API, отколкото от всичко друго. Затова нека се потопим в конкретни случаи на употреба.

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

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

Консумиране на публичен API за получаване на данни

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

Ще използваме API за кучета!

Не само че е забавен API, но и не изисква никаква автентификация.

Плюс това е HTTP REST API. Това означава, че е уеб базиран API. Тъй като е обвързан с тази среда, тя изисква да се съобразим с някои от спецификата на протокола.

В този случай това означава използването на HTTP глаголи като GET, PUT, POST, DELETE.

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

Да запалим Пощальон и да видим как изглежда потребителският му интерфейс.

Моят потребителски интерфейс използва тъмната тема, така че може леко да се различава от вашия.

Първоначално тук може да се усвои много информация, така че нека започнем с VERB и URL.

Глаголът по подразбиране трябва да бъде GET. Ако е така, можете да го запазите по този начин и да въведете следния URL адрес: https://dog.ceo/api/breeds/list/all

Натиснете „Изпрати“ и чукайте! Трябва да получите отговор със съответните данни. Готово! Току-що направихте първото си обаждане в API.

Сега за този пример няма да използваме нито една от получените данни. Но вие получавате идеята. Можете да покажете различни породи кучета на вашия потребител и да покажете изображение на дадена порода, ако кликнете върху нея.

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

Страхотен факт: този малък проект също е с отворен код, така че можете да погледнете под капака тук.

Работа с удостоверяване с частен API

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

Тук ще използваме само код за взаимодействие с API на Snipcart. Можете да затворите Пощальон, но го поддържайте удобно. Добре е да използвате такъв инструмент, когато започнете с API.

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

Създайте нова папка за този проект. Използвайте npm init в папката и стартирайте текстовия редактор.

Сега създайте файл index.js, след което отворете package.jsonfile. В него добавете следните редове в обекта от най-високо ниво:

"bin": {"отстъпки": "./index.js"}

Ще се нуждаем и от пакета на командира, за да анализираме входовете от клиента. Изпълнете npm install --запишете командира в текущата папка.

Ще използваме и малък lib, за да създадем идентификационни номера. Можете да го инсталирате с npm install --save shorttid.

Докато сме в това, нека да пуснем и npm install - запази либа за заявка. Това ще ни улесни извършването на HTTP обаждания. Върнете се обратно във файла си index.js и поставете този код:

Нека се фокусираме върху функцията за заявка тук.

Това е мястото, където осъществяваме външното обаждане на API към Snipcart. Можете да видите, че предаваме метода: „POST“ на метода. Това е така, защото искаме да изпратим данни към API на Snipcart. Като уточнява този метод, API ще картографира действието правилно. Това позволява да прочете тялото на заявката, където се намират данните за отстъпките.

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

Другите ни примери бяха всички на публичните API. Те не изискват удостоверяване.

Но в реалния живот повечето API-та, които ще използвате, вероятно ще изискват известно удостоверяване. Това е стандартен „модел“ в света на API. Нашите клиенти няма да се радват, ако позволим на някой да създава отстъпки в магазина си! )

За нашата цел предаваме ключа API директно в заявката.

Ура - сървърът ни разпознава! След това той може да изпълни заявката, обхваната само за нашия акаунт.

Ако искате да тествате нашето малко приложение, можете да стартирате npm install -g в директорията на проекта. След това просто стартирайте отстъпки x, за да създадете отстъпки x брой пъти.

Можете да отидете в таблото за управление на Snipcart (завинаги безплатни акаунти в тестов режим) и да се убедите сами, че отстъпките са създадени правилно.

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

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

Затварящи мисли

Искрено се надявам този грунд да ви помогне да разберете по-добре какво представляват API-тата и как можете да ги използвате в работния процес на развитие.

Няколко поемания:

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

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

Има много неща, които бихме могли да подобрим. Например:

  • Оставяне на потребителя да избере вида на отстъпката
  • Можем също да изпратим създадените кодове по имейл директно в същата функция, вместо просто да ги регистрираме.
  • Ако имахме напреднали нужди от нашите инструменти за отстъпки, сами бихме могли да напишем API. Оттам дори бихме могли да създадем потребителски интерфейс, който взаимодейства с нашия API, ако искаме. Както и да е, надявам се да получите идеята сега.! :)

И каква е следващата стъпка? Както почти всичко в сферата на разработката, ще трябва да кодирате, код, код и още малко! Ето как ще се запознаете с управлението и интеграцията на API.

След известно време ще станете ефективни с тях.

И там започва истинското забавление.

Ако ви е харесала тази публикация, моля, отделете секунда, за да я ръкопляскате и споделите в Twitter. Имате коментари, въпроси? Натиснете секцията по-долу!

Първоначално публикувах това в блога Snipcart и го споделих в нашия бюлетин.