Простое объяснение Web API на примере продажи фермерских продуктов
Перевод статьи «Web APIs explained by selling goods from your farm».
Если вам случалось бывать на продуктовом рынке или на ярмарке, вы вполне сможете понять концепцию API (англ. application programming interface, варианты перевода — прикладной интерфейс приложения или программный интерфейс приложения).
Даже начинающим программистам, скорее всего, неоднократно встречалась аббревиатура «API».
Понять концепцию прикладного интерфейса приложения (API) может быть довольно сложно, если вы не знакомы с такими концепциями как SOAP, HTTP и XML.
Я решил найти способ объяснить работу web API в целом. Таким образом, когда вы углубитесь в технические детали, у вас уже будет понимание того, как это работает все вместе.
В этом руководстве вы будете собственником фермы, который продает пять видов продуктов: курятину, свинину, яйца, помидоры и кукурузу.
Чтобы разобраться в этой статье, вам нужно понимать разницу между бэкендом и фронтендом приложений. Если вы с этой темой пока не знакомы, можно для начала почитать мою статью о GET/POST.
Разница между GUI и API
Давайте начнем со знакомого способа использования веба. Браузер, скажем, Chrome, это пример графического пользовательского интерфейса (GUI). Вы как пользователь можете взаимодействовать с дружественным к вам инструментом для решения ваших задач. Например, при помощи браузера вы можете заказывать билеты на самолет или искать что-то в Google.
Графический пользовательский интерфейс (GUI) позволяет посетителям сайта взаимодействовать с кодом на сервере контролируемым и структурированным образом.
Если провести аналогию с фермой, то GUI будет прилавком на рынке или стендом на ярмарке.
Если вы будете просто держать свои товары на складе, позволяя пользователям заходить туда, много вы не заработаете. Вместо этого нужно поставить киоск или палатку и разложить там товар, чтобы покупатели могли быстро понять, чем вы торгуете и сколько это стоит.
Таким образом покупатели «взаимодействуют» с плодами вашего тяжелого труда. Им не нужно разбираться в процессе выращивания овощей, не нужно знать, какими инструментами вы при этом пользуетесь. Они просто видят конечный продукт.
Обратите внимание, что опыт каждого отдельного покупателя это личное взаимодействие, один на один. Если покупатель пришел в вашу палатку, н хочет купить товары именно с вашей фермы.
Что такое API?
Помимо прямых продаж потребителям есть и другие способы продавать продукты. Вы можете продавать свои товары дистрибьюторам и местным ресторанам, а они используют их в различных блюдах или продадут в продуктовые магазины.
Для потребителя это новый способ «употребить» ваш продукт. Он может и не знать, чьи яйца использовались для приготовления омлета, заказанного им на завтрак в ресторане, но он все равно «потребляет» ваш продукт.
Но с точки зрения собственника фермы это совершенно другая процедура продаж. Теперь вам не нужно заботливо оформлять свою палатку и раскладывать товары для покупателей. Вместо этого вам, вероятно, понадобится подъезд к складу, чтобы дистрибьюторы и рестораторы могли подъезжать грузовиками и загружаться. Также вам нужно упаковать ваши товары для оптовых продаж.
Вот это уже близко к концепции API. Создавая API, вы даете возможность другим разработчикам иметь доступ к вашим данным и использовать их в своих приложениях.
Как клиенты ресторана могут употребить яйца ваших кур, заказав омлет, так и пользователи сайтов могут «потребить» ваш продукт на чьем-то еще сайте при помощи виджета или кода на серверах другой компании.
Теперь у нас есть новый уровень взаимодействия. Ваши дистрибьюторы и рестораторы могут взаимодействовать с вами лично, посещая ферму, но затем они предлагают ваши продукты тысячам покупателей.
Вам как собственнику фермы все равно нужно налаживать процессы продаж, чтобы успешно обслуживать дистрибьюторов. Аналогично, API это структурированный способ использования вашего бэкенд-кода другими людьми. У вас как разработчика по-прежнему сохраняется полный контроль.
На иллюстрации в качестве примера я использовал виджет поиска, но на самом деле для доступа к API может использоваться что угодно. Это лишь распространенный пример использования на сайтах сторонних API. Но есть и другие примеры:
К чему можно получить доступ при помощи API?
Скажем, вы хотите начать продавать дистрибьюторам и рестораторам яйца со своей фермы. Для этого вам нужно будет наладить кое-какие процессы. Вам понадобится:
Прежде чем начать всем этим заниматься, вы должны понять, готовы ли вы вообще принимать оптовые заказы на яйца. Есть ли у вас достаточно кур, чтобы еженедельно производить нужное количество яиц? Если ваша система попросту не готова к массовому производству, яйца у вас быстро кончатся, а клиенты разочаруются.
Разработчики API создают endpoints (конечные точки), позволяющие другим разработчикам получать доступ к конкретным данным в базе данных. В приведенном выше примере это был бы endpoint «яйца». Если вы не создадите endpoint, ваши клиенты просто не смогут купить у вас яйца.
Вы можете установить отдельные endpoints для каждого вида продуктов вашей фермы: для курятины, яиц, свинины, помидоров и кукурузы. Некоторые продукты могут быть доступны только на рынке (GUI), потому что вы не уверены, что потянете производство этих продуктов для оптовых продаж.
В этом заключается разница между API и базой данных с открытым исходным кодом. В такой базе данных можно создать любой запрос и получить доступ к любым данным. Когда вы создаете API для вашего бэкенда, вы создаете endpoints, которые открывают только определенные данные.
Как собственник фермы вы контактируете не с потребителями напрямую, а с дистрибьюторами. В разработке роль таких дистрибьюторов играют разработчики из других компаний, взаимодействующие с вашим API. Когда они напишут код для доступа к данным с вашего сервера, посетители их сайта смогут получить какие-то новые услуги, основанные на ваших данных.
Рассматриваем отдельный вызов API
Допустим, вы решили создать endpoint для яиц на вашей ферме. Местный ресторан хочет покупать по 1000 яиц, чтобы иметь возможность готовить омлеты, которые еженедельно заказывают 1000 раз.
Обратите внимание, что вызов API начинается с запроса пользователя. Если смотреть на описание, это может не быть очевидным.
Отдельный вызов API происходит, когда срабатывает какой-то триггер в результате чего другой разработчик отсылает запрос к вашему API на определенный endpoint. Ваш API должен доставить ответ, основанный на вашем бэкенд-коде.
В аналогии с фермой триггером является заказ 1000 яиц. Менеджер ресторана уже договорился с вашей фермой о поставках. А ваша ферма уже создала все условия для отправки 1000 яиц за раз.
Таким образом, когда поступает заказ на 1000 яиц, ваша ферма доставляет ответ: 1000 яиц.
Имейте в виду, что договориться с вашей фермой о поставках могли 100 разных ресторанов, и 10 из них могут прислать заказы одновременно! Здесь в игру вступает масштабируемость. Вы должны определиться, готов ли ваш сервер удовлетворить такой спрос. Но это тема для другой статьи.
Вот техническая версия описанной выше последовательности. Здесь у вас есть картографическое приложение, которое может использоваться на сайтах (как Google Maps).
Конечно, ваш картографический виджет может использоваться на 1000 других веб-приложений, так что нужно быть готовым обслуживать все эти вызовы API!
Примеры GET и POST
Пока что в наших примерах с фермой были сценарии, напоминающие запросы GET. Когда посетители ресторана делают заказы, ресторан посылает грузовик на вашу ферму, чтобы забрать яйца.
Но как насчет запросов POST? Если обратиться к примерам из жизни, API Facebook позволяет пользователям других приложений создавать посты, а затем эти приложения могут отправлять созданные посты прямо на Facebook для моментальной публикации.
В некоторых случаях, как с API соцсетей, может иметь смысл позволить конечным пользователям постить что-либо в социальной сети прямо из стороннего приложения.
Но есть и другой пример. API Amazon позволяет собственникам онлайн-магазинов публиковать информацию об их товарах на торговой площадке Amazon. В такой ситуации разработчик независимого онлайн-магазина также может реализовать присутствие этого магазина на Amazon. В этом случае API никак не будет связан с конечными пользователями или посетителями сайта.
В нашем примере с фермой это похоже на обработку ежемесячных счетов. После того как дистрибьюторы и рестораторы весь месяц посещали вашу ферму и покупали продукты, вы в конце месяца выставляете им счет, где расписываются все нужные платежи.
Ресторан должен не только вовремя забирать нужные ему яйца и разработать для этого особую процедуру. Он также должен обеспечить своевременную оплату по вашему счету. Здесь, вероятно, будет участвовать их бухгалтер. Скажем, бухгалтер знает, что ресторан должен платить вам первого числа каждого месяца.
Как пользователь (покупатель) может запустить триггер для запроса POST? Представим, что ресторан немедленно отправляет вам платеж каждый раз, как кто-то заказывает продукты с вашей фермы. Если человек заказал омлет за 5 долларов, 2 доллара причитаются вашей ферме за яйца, и ресторан немедленно переводит их на ваш банковский счет. Если бы это было веб-приложение, такой уровень коммуникации мог бы сработать, но поскольку это ферма, подобный порядок был бы слишком непрактичным.
Разница между фермой и веб-приложением
Как видно из предыдущего примера, между цепочкой поставок на ферме и вызовом API есть существенная разница. Тайминг.
По причинам, связанным с логистикой, мы не можем надеяться на то, что на ферме все будет так же мгновенно, как при большинстве вызовов API, даже если шаги, в принципе, те же самые.
Давайте рассмотрим пример запроса GET, который мы уже разбирали ранее.
Применительно к веб-разработке здесь происходит следующее:
Но если проводить аналогию с фермой,
Было бы невероятно непрактично посылать грузовик на ферму за каждой парой яиц (хотя это был бы самый свежий омлет в истории человечества). Но шаги те же самые. Я просто хотел бы подчеркнуть разницу в тайминге.
А вот когда пользователь веб-приложения производит какое-то действие, запускающее отправку запроса, обычно он получает ответ немедленно.
Что означает «открыть API»?
Вернемся к одному из вопросов начала статьи. Что происходит, когда компания «открывает свой API»?
Это значит, что на сервере этой компании есть какие-то ценные данные, к которым теперь можно получить доступ через определенные endpoints. Компании нужно определить, каким образом разработчики из других компаний могут получать их данные, но в то же время они делают эти данные (в структурированном виде) доступными широкой общественности.
В аналогии с фермой открытие API это момент, когда ваша ферма решает продавать свою продукцию дистрибьюторам и рестораторам и готовит все свои внутренние системы для обработки оптовых заказов.
API vs GUI (What are the Differences?)
Last Updated on September 14, 2020 by RapidAPI Staff Leave a Comment
API vs. GUI
Application Programming Interface (API) and Graphical User Interface (GUI) are two phrases that are common in the realm of technology and software development. And since the two terms help facilitate interactions between users and computer applications, they can somehow confuse developers who are green in software development. In this article, we’ll try to explain the meaning of the two phrases and highlight their differences.
What is an API?
API is the acronym for Application Programming Interface, which refers to a set of routines, protocols, tools, and definitions that allow communication between technology products such as applications and websites. APIs allow applications to interact and communicate with an external server using some simple commands. Using APIs, developers can create streamlined processes that don’t keep re-inventing the wheel or building functionalities that already in existence. They help programmers to add new features to applications, and improve the speed and efficiency of the development process.
Currently, APIs have become part and parcel of anything that relies on technology. You’ll find APIs for nearly any category, whether it is business, sports, or travel.
Let’s use a non-technical example to help you understand more about APIs
When you go out and visit a restaurant, you make your order to the waiter who, in turn, takes it and sends it to the kitchen. When the food is fully prepared in the kitchen, the waiter collects the food and brings it to your table. In this case, you are the first computer application and the application you’re communicating with is the kitchen. The waiter is the API as they facilitate the interaction between the customer (first app) and the kitchen (the other app).
Technical examples
Let’s consider ecommerce websites. Rather than creating their payment processing systems, they leverage the vast array of payment processing APIs in the market.
Another example by signing up for the ride and share app, you can map your route, find a driver, and pay for the trip.
You can also integrate your application to Instagram using the Instagram API.
With an eBay API, merchants can upload items for sale on ebay.com, rather than doing it manually using the eBay’s GUI.
What is a GUI?
An abbreviation for Graphical User Interface, GUI refers to a software platform that displays back-end data in a visually coherent way to help users interact with a computer application. It presents objects that convey information and represent actions that the user can take. GUI allows you to use picture-like items, such as icons, cursors, and buttons, to tell a computer operating system what you want. Using these objects, GUI allows you to navigate to different parts of an application.
Users interact with the GUI using a mouse, but the latest devices, such as mobile phones, utilize the touch-screen technology. You can also navigate a Graphical User Interface using a keyboard.
Examples of GUI
GUI powers most of the operating systems that we use today. These include:
Other examples include:
Main differences between APIs and GUIs
While an API permits the communication between two programs, GUI allows interaction between a human and a computer program.
Complexity
The other difference between API and GUI is the level of expertise required to work with each. GUI doesn’t require too much technical know-how or the need to memorize different methods and languages. On the other hand, APIs require high technical skills to leverage. You need to understand various coding languages, as well as learn various techniques of making API requests.
Additionally, while GUI requires few resources, API requires a lot of things, including back-end storage that is backed by a logical architecture, a library of scripts, and regular management.
Time Factor
Both GUI and API can be used for testing application functionality. However, unlike APIs which are swift in action, Graphical User Interface tests tend to take longer.
Price Range
A Graphical User Interface is generally expensive than an API as it comes as a complete package. However, it is crucial to remember that GUIs costs reflect their quality and uniqueness in the market.
Additionally, unlike Graphical User Interfaces that are subscription-based, APIs are call-based, and hence they give you precisely what you ask for. This means that with an API, you pay for raw materials as opposed to a finished product.
Language-Independent
Unlike GUI, API allows the exchange of data through XML or JSON, thus making it possible for any core language to be used for automation. However, you need all your data in one place to use API, as it allows more flexibility when it comes to automation and innovation.
воскресенье, 17 января 2021 г.
Unit, API и GUI тесты — чем отличаются
Давайте рассмотрим стандартную пирамиду автоматизации
Если говорить о программе:
Начинаем писать тесты снизу, потому что сначала логичнее проверить небольшой участок кода, а потом усложнять:
В качестве аналогии давайте рассмотрим создание платья. Вот я заказала себе платье по фигуре. Мастер выслушает мои пожелания, снимет мерки, а потом приступит за работу. Сначала он сделает выкройку и раскроит ткань. Если проверять каждую деталь, сравнивая с выкройкой — это будут юнит-тесты.
Проверили каждую деталь отдельно? Теперь тестируем вместе. Обметали и смотрим — ровно? Криво? Может, что-то подправить?
Это аналог api-тестов — платье еще не готово, это не конечный продукт. Но мы соединили отдельные детали вместе и смотрим, как они работают.
Если всё хорошо, можно шить! А дальше следуюет аналог UI-тестов — последняя проверка, когда платье уже готово.
Нигде не накосячили? Когда все вместе собрано и рукав к попе пришит, переделывать уже очень трудно и дорого, такие проблемы лучше обнаружить заранее.
А еще одну аналогию можно провести с танцами.
Начинаем с основ. Сначала надо отработать движение, чтобы потом внедрять его в танец. Каждое конкретное движение — аналог unit-тестов.
Следующий этап — связать отдельные функции вместе. Зная 5 разных движений, мы начинаем связывать их под музыку. Это аналог api-тестов.
Каждую часть танца мы разрабатываем отдельно (как и разные куски api в программе).
А потом уже соединяем всё вместе. И получается готовый танец. Аналог UI-тестов.
Итого
Соберем всё вместе. В программе:
Что такое API
Содержание
— А зачем это мне? Я вообще-то web тестирую! Вот если пойду в автоматизацию, тогда да… Ну, еще это в enterprise тестируют, я слышал…
А вот и нет! Про API полезно знать любому тестировщику. Потому что по нему системы взаимодействуют между собой. И это взаимодействие вы видите каждый день даже на самых простых и захудалых сайтах.
Любая оплата идет через API платежной системы. Купил билет в кино? Маечку в онлайн-магазине? Книжку? Как только жмешь «оплатить», сайт соединяет тебя с платежной системой.
Но даже если у вас нет интеграции с другими системами, у вас всё равно есть API! Потому что система внутри себя тоже общается по api. И пока фронт-разработчик усиленно пилит GUI (графический интерфейс), вы можете:
Что такое API
API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».
Если переводить на русский, это было бы слово «договор». Договор между двумя сторонами, как договор на покупку машины:
API — набор функций
Когда вы покупаете машину, вы составляете договор, в котором прописываете все важные для вас пункты. Точно также и между программами должны составляться договоры. Они указывают, как к той или иной программе можно обращаться.
Соответственно, API отвечает на вопрос “Как ко мне, к моей системе можно обратиться?”, и включает в себя:
Тут вы можете мне сказать:
— Хмм, погоди. Операция, данные на входе, данные на выходе — как-то всё это очень сильно похоже на описание функции!
Если вы когда-то сталкивались с разработкой или просто изучали язык программирования, вы наверняка знаете, что такое функция. Фактически у нас есть данные на входе, есть данные на выходе, и некая магия, которая преобразует одно в другое.
И да! Вы будете правы в том, что определения похожи. Почему? Да потому что API — это набор функций. Это может быть одна функция, а может быть много.
Как составляется набор функций
Да без разницы как. Как разработчик захочет, так и сгруппирует. Например, можно группировать API по функционалу. То есть:
Можно не группировать вообще, а делать одно общее API.
Можно сделать одно общее API, а остальные «под заказ». Если у вас коробочный продукт, то в него обычно входит набор стандартных функций. А любые хотелки заказчиков выносятся отдельно.
Получается, что в нашей системе есть несколько разных API, на каждое из которых у нас написан контракт. В каждом контракте четко прописано, какие операции можно выполнять, какие функции там будут
И конечно, функции можно переиспользовать. То есть одну и ту же функцию можно включать в разные наборы, в разные апи. Никто этого не запрещает.
Получается, что разработчик придумывает, какое у него будет API. Либо делает общее, либо распределяет по функционалу или каким-то своим критериям, и в каждое апи добавляет тот набор функций, который ему необходим.
При чем тут слово «интерфейс»
— Минуточку, Оля! Ты же сама выше писала, что API — это Application programming interface. Почему ты тогда говоришь о контракте, хотя там слово интерфейс?
Да потому, что в программировании контракт — это и есть интерфейс. В классическом описании ООП (объектно-ориентированного программирования) есть 3 кита:
Не всегда программа предоставляет именно графический интерфейс. Это может быть SOAP, REST интерфейс, или другое API. Чтобы использовать этот интерфейс, вы должны понимать:
Как вызывается API
Вызвать апи можно как напрямую, так и косвенно.
Вызов API напрямую
1. Система вызывает функции внутри себя
Разные части программы как-то общаются между собой. Они делают это на программном уровне, то есть на уровне API!
Это самый «простой» в использовании способ, потому что автор API, которое вызывается — разработчик. И он же его потребитель! А значит, проблемы с неактуальной документацией нет =)
Шучу, проблемы с документацией есть всегда. Просто в этом случае в качестве документации будут комментарии в коде. А они, увы, тоже бывают неактуальны. Или разработчики разные, или один, но уже забыл, как делал исходное api и как оно должно работать…
2. Система вызывает метод другой системы
А вот это типичный кейс, которые тестируют тестировщики в интеграторах. Или тестировщики, которые проверяют интеграцию своей системы с чужой.
Одна система дергает через api какой-то метод другой системы. Она может попытаться получить данные из другой системы. Или наоборот, отправить данные в эту систему.
Допустим, я решила подключить подсказки из Дадаты к своему интернет-магазинчику, чтобы пользователь легко ввел адрес доставки.
Я подключаю подсказки по API. И теперь, когда пользователь начинает вводить адрес на моем сайте, он видит подсказки из Дадаты. Как это получается:
И, конечно, не забываем про кейс, когда мы разрабатываем именно API-метод. Который только через SOAP и можно вызвать, в интерфейсе его нигде нет. Что Заказчик заказал, то мы и сделали ¯\_(ツ)_/¯
Пример можно посмотреть в Users. Метод MagicSearch создан на основе реальных событий. Хотя надо признать, в оригинале логика еще замудренее была, я то под свой сайт подстраивала.
Но тут фишка в том, что в самой системе в пользовательском интерфейсе есть только обычный поиск, просто строка ввода. Ну, может, парочка фильтров. А вот для интеграции нужна была целая куча доп возможностей, что и было сделано через SOAP-метод.
Функционал супер-поиска доступен только по API, пользователь в интерфейсе его никак не пощупает.
В этом случае у вас обычно есть ТЗ, согласно которому работает API-метод. Ваша задача — проверить его. Типичная задача тестировщика, просто добавьте к стандартным тестам на тест-дизайн особенности тестирования API, и дело в шляпе!
(что именно надо тестировать в API — я расскажу отдельной статьей чуть позднее)
3. Человек вызывает метод
Для примера снова идем в Users. Если мы хотим создать пользователя, надо заполнить уйму полей!
Конечно, это можно сделать в помощью специальных плагинов типа Form Filler. Но что, если вам нужны адекватные тестовые данные под вашу систему? И на русском языке?
Заполнение полей вручную — грустно и уныло! А уж если это надо повторять каждую неделю или день на чистой тестовой базе — вообще кошмар. Это сразу первый приоритет на автоматизацию рутинных действий.
И в данном случае роль автоматизатора выполняет… Postman. Пользователя можно создать через REST-запрос CreateUser. Один раз прописали нормальные “как настоящие” данные, каждый раз пользуемся. Профит!
Вместо ручного заполнения формы (1 минута бездумного заполнения полей значениями «лпрулпк») получаем 1 секунду нажатия на кнопку «Send». При этом значения будут намного адекватнее.
А еще в постмане можно сделать отдельную папку подготовки тестовой базы, напихать туда десяток запросов. И вот уже на любой базе за пару секунд вы получаете столько данных, сколько вручную вбивали бы часами!
Если вы нашли баг и не понимаете, на кого его вешать — разработчика front-end или back-end, уберите все лишнее. Вызовите метод без графического интерфейса. А еще вы можете тестировать логику программы, пока интерфейс не готов или сломан.
4. Автотесты дергают методы
Есть типичная пирамида автоматизации:
Слово API как бы намекает на то, что будет использовано в тестах ツ
GUI-тесты — честный тест, робот делает все, что делал бы пользователь. Открывает браузер, тыкает на кнопочки… Но если что-то упадет, будете долго разбираться, где именно.
API-тесты — все то же самое, только без браузера. Мы просто подаем данные на вход и проверяем данные на выходе. Например, можно внести итоговый ответ в эксельку, и пусть робот выверяет ее, правильно ли заполняются данные? Локализовать проблему становится проще.
Unit-тесты — это когда мы проверяем каждую функцию отдельно. Отдельно смотрим расчет для ячейки 1, отдельно — для ячейки 2, и так далее. Такие тесты шустрее всего гоняются и баги по ним легко локализовать.
Косвенный вызов API
Когда пользователь работает с GUI, на самом деле он тоже работает с API. Просто не знает об этом, ему это просто не нужно.
То есть когда пользователь открывает систему и пытается загрузить отчет, ему не важно, как работает система, какой там magic внутри. У него есть кнопочка «загрузить отчет», на которую он и нажимает. Пользователь работает через GUI (графический пользовательский интерфейс).
Но на самом деле под этим графическим пользовательским интерфейсом находится API. И когда пользователь нажимает на кнопочку, кнопочка вызывает функцию построения отчета.
А функция построения отчета уже может вызывать 10 разных других функций, если ей это необходимо.
И вот уже пользователь видит перед собой готовый отчет. Он вызвал сложное API, даже не подозревая об этом!
Что значит «Тестирование API»
В первую очередь, мы подразумеваем тестирование ЧЕРЕЗ API. «Тестирование API» — общеупотребимый термин, так действительно говорят, но технически термин некорректен. Мы не тестируем API, мы не тестируем GUI (графический интерфейс). Мы тестируем какую-то функциональность через графический или программный интерфейс.
Но это устоявшееся выражение. Можно использовать его и говорить “тестирование API”. И когда мы про это говорим, мы имеем в виду:
Когда мы говорим про тестирование API, чаще всего мы подразумеваем тестирование Remote API. Когда у нас есть две системы, находящихся на разных компьютерах, которые как-то между собой общаются.
И если вы видите в вакансии «тестирование API», скорее всего это подразумевает умение вызвать SOAP или REST сервис и протестировать его. Хотя всегда стоит уточнить!
Резюме
API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».
