Перевод статьи «Web APIs explained by selling goods from your farm».
Если вам случалось бывать на продуктовом рынке или на ярмарке, вы вполне сможете понять концепцию API (англ. application programming interface, варианты перевода — прикладной интерфейс приложения или программный интерфейс приложения).
Даже начинающим программистам, скорее всего, неоднократно встречалась аббревиатура «API».
- «Не могу дождаться, когда уже эта компания выпустит свой публичный API!»
- «API этой компании это какой-то бардак!»
- «Есть у них в API endpoint для этих данных?»
Понять концепцию прикладного интерфейса приложения (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).
- Какой-то пользователь на каком-то чужом сайте использует ваше картографическое приложение и осуществляет действие, для которого требуются данные с вашего сервера.
- Разработчик этого сайта уже написал код, который создаст запрос к вашему API, основываясь на действиях пользователя.
- Происходит вызов API, и ваш сервер доставляет ответ.
Конечно, ваш картографический виджет может использоваться на 1000 других веб-приложений, так что нужно быть готовым обслуживать все эти вызовы API!
Примеры GET и POST
Пока что в наших примерах с фермой были сценарии, напоминающие запросы GET. Когда посетители ресторана делают заказы, ресторан посылает грузовик на вашу ферму, чтобы забрать яйца.
Но как насчет запросов POST? Если обратиться к примерам из жизни, API Facebook позволяет пользователям других приложений создавать посты, а затем эти приложения могут отправлять созданные посты прямо на Facebook для моментальной публикации.
В некоторых случаях, как с API соцсетей, может иметь смысл позволить конечным пользователям постить что-либо в социальной сети прямо из стороннего приложения.
Но есть и другой пример. API Amazon позволяет собственникам онлайн-магазинов публиковать информацию об их товарах на торговой площадке Amazon. В такой ситуации разработчик независимого онлайн-магазина также может реализовать присутствие этого магазина на Amazon. В этом случае API никак не будет связан с конечными пользователями или посетителями сайта.
В нашем примере с фермой это похоже на обработку ежемесячных счетов. После того как дистрибьюторы и рестораторы весь месяц посещали вашу ферму и покупали продукты, вы в конце месяца выставляете им счет, где расписываются все нужные платежи.
Ресторан должен не только вовремя забирать нужные ему яйца и разработать для этого особую процедуру. Он также должен обеспечить своевременную оплату по вашему счету. Здесь, вероятно, будет участвовать их бухгалтер. Скажем, бухгалтер знает, что ресторан должен платить вам первого числа каждого месяца.
Как пользователь (покупатель) может запустить триггер для запроса POST? Представим, что ресторан немедленно отправляет вам платеж каждый раз, как кто-то заказывает продукты с вашей фермы. Если человек заказал омлет за 5 долларов, 2 доллара причитаются вашей ферме за яйца, и ресторан немедленно переводит их на ваш банковский счет. Если бы это было веб-приложение, такой уровень коммуникации мог бы сработать, но поскольку это ферма, подобный порядок был бы слишком непрактичным.
Разница между фермой и веб-приложением
Как видно из предыдущего примера, между цепочкой поставок на ферме и вызовом API есть существенная разница. Тайминг.
По причинам, связанным с логистикой, мы не можем надеяться на то, что на ферме все будет так же мгновенно, как при большинстве вызовов API, даже если шаги, в принципе, те же самые.
Давайте рассмотрим пример запроса GET, который мы уже разбирали ранее.
Применительно к веб-разработке здесь происходит следующее:
- Пользователь осуществляет какое-то действие, запускающее запрос.
- Код бэкенда направляет вызов API к endpoint.
- API доставляет нужную информацию.
Но если проводить аналогию с фермой,
- Пользователь заказывает омлет.
- Ресторан посылает грузовик забрать яйца с вашей фермы.
- Яйца доставляются в ресторан и из них готовится омлет.
Было бы невероятно непрактично посылать грузовик на ферму за каждой парой яиц (хотя это был бы самый свежий омлет в истории человечества). Но шаги те же самые. Я просто хотел бы подчеркнуть разницу в тайминге.
А вот когда пользователь веб-приложения производит какое-то действие, запускающее отправку запроса, обычно он получает ответ немедленно.
Что означает «открыть API»?
Вернемся к одному из вопросов начала статьи. Что происходит, когда компания «открывает свой API»?
Это значит, что на сервере этой компании есть какие-то ценные данные, к которым теперь можно получить доступ через определенные endpoints. Компании нужно определить, каким образом разработчики из других компаний могут получать их данные, но в то же время они делают эти данные (в структурированном виде) доступными широкой общественности.
В аналогии с фермой открытие API это момент, когда ваша ферма решает продавать свою продукцию дистрибьюторам и рестораторам и готовит все свои внутренние системы для обработки оптовых заказов.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
