Определение APIруководство для начинающих по API

Вы пользуетесь API десятки раз в день, не замечая этого. Проверка погоды на телефоне, отправка сообщения, оплата покупки онлайн: каждое из этих действий незаметно передаёт запрос API и ждёт ответа. Слово звучит как что-то из глубокой инфраструктуры, но идея за ним проста, и когда она становится понятной, API начинаешь замечать повсюду.

Это руководство даёт рабочее определение API как в простых словах, так и в технических терминах, а затем объясняет, как API на самом деле перемещают данные: запросы и ответы, эндпоинты, методы, аутентификация и JSON, который они возвращают. Далее рассматриваются основные стили, с которыми вы столкнётесь (REST, SOAP, GraphQL и вебхуки), приводятся реальные примеры и показывается, как скрейпинговый API превращает беспорядочный сайт без официального API во что-то, что можно вызывать как настоящий API.

Определение API: что такое API на самом деле

API (Application Programming Interface, интерфейс прикладного программирования), это набор правил, позволяющих двум программам общаться между собой. Одна программа запрашивает что-то; другая отвечает в предсказуемом формате. API, это согласованный контракт посередине, описывающий, как спрашивать и что получишь в ответ.

Классическая аналогия: ресторан. Вы сидите за столиком (ваше приложение), изучаете меню доступных блюд (задокументированные возможности API) и говорите официанту, что хотите. Официант (API) относит ваш заказ на кухню (сервер), ждёт, пока его приготовят, и приносит результат обратно к вашему столику. Вы никогда не заходите на кухню и вам не нужно знать, как готовится блюдо. Нужно лишь знать, что есть в меню и как это заказать.

В технических терминах API предоставляет определённый интерфейс к данным или функциям системы, скрывая за ним реализацию. Он абстрагирует базу данных, бизнес-логику и внутренний код, предоставляя внешнему миру стабильный набор операций для вызова. Эта абстракция и есть вся ценность: кухня может полностью изменить свои рецепты, и пока меню остаётся прежним, ваш столик этого не заметит.

Как работает API: запрос и ответ

Почти каждый API работает по одному и тому же простому циклу: клиент отправляет запрос, сервер возвращает ответ. Всё остальное, детали поверх этого паттерна. Разберите части, и остальная часть статьи сложится сама собой.

Запрос

Запрос, это сообщение, которое ваша программа отправляет API, говоря, что ей нужно. Типичный запрос к веб-API содержит четыре вещи: какой адрес запрашивать (эндпоинт), какое действие вы хотите выполнить (метод), кто вы (аутентификация) и иногда тело данных, которые вы отправляете.

Ответ

Ответ, это то, что приходит обратно. Обычно он включает код статуса, сообщающий о результате (200 означает успех, 404 означает «не найдено», 401 означает «не авторизован»), и тело с запрошенными данными, чаще всего в формате JSON. Ваш код читает этот ответ и делает с ним что-то полезное.

Эндпоинты

Эндпоинт, это конкретный адрес для обращения к конкретному ресурсу или действию. Если API, это меню, то эндпоинты, отдельные позиции в нём. Погодный API может предоставлять один эндпоинт для текущих условий и другой для прогноза на пять дней. Эндпоинты обычно делятся на несколько знакомых типов:

• Эндпоинты ресурсов возвращают конкретную вещь, например один профиль пользователя или один товар.
• Коллекционные эндпоинты возвращают группу вещей, например список всех товаров.
• Эндпоинты действий выполняют операцию, например обрабатывают платёж или отправляют email.
• Поисковые эндпоинты позволяют запрашивать и фильтровать, например находить все заказы за эту неделю.

Методы

Метод говорит API, что вы намереваетесь сделать с эндпоинтом. Веб-API заимствуют эти глаголы напрямую из HTTP, и четыре из них покрывают большую часть того, что вам придётся писать:

• GET читает данные, ничего не меняя (получить профиль).
• POST создаёт что-то новое (отправить новый заказ).
• PUT обновляет существующую вещь (редактировать профиль).
• DELETE удаляет что-то (отменить заказ).

Аутентификация

Большинству полезных API нужно знать, кто звонит, прежде чем ответить. Аутентификация, это API, проверяющий вашу личность у двери. Простейшая форма, ключ API: длинная секретная строка, включаемая в каждый запрос и идентифицирующая ваш аккаунт, как ключ от двери, открывающий только одну конкретную дверь. Токены идут на шаг дальше: они больше похожи на смарт-карту, несущую также информацию о том, что вам разрешено делать, а стандарты вроде OAuth 2.0 используют их для более богатого, разрешительного доступа. Правильный выбор, это баланс. Простой ключ API вполне достаточен для простого внутреннего инструмента, тогда как публичное, ориентированное на пользователя приложение обычно требует более строгих гарантий, предоставляемых токенами и OAuth.

JSON: формат, на котором говорит большинство ответов

Когда API отвечает, ему нужно отформатировать данные так, чтобы ваша программа могла их надёжно прочитать. JSON (JavaScript Object Notation) стал стандартом, поскольку компактен, читаем человеком и поддерживается каждым современным языком. Он представляет данные в виде пар ключ-значение и вложенных списков, что аккуратно соответствует объектам, с которыми большинство программ уже работает. Небольшой JSON-ответ для одного пользователя может выглядеть так:

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "[email protected]",
  "active": true
}

Сложите части вместе, и полный круговой обмен читается почти как предложение: отправить GET-запрос на эндпоинт пользователей с ключом API и получить обратно JSON. Вот та же идея в виде однострочной команды для терминала плюс тип возвращаемого ответа.

# GET a user, sending an API key as a header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.example.com/users/42"

Сервер читает запрос, проверяет ключ, находит пользователя 42 и отвечает приведённым выше JSON-объектом. Это весь механизм большинства API, с которыми вам когда-либо придётся работать.

Типы API: REST, SOAP, GraphQL и вебхуки

API следуют нескольким распространённым стилям. Все они выполняют одну и ту же задачу запрос-ответ, но различаются степенью строгости, способом запроса данных и форматом возвращаемых данных. Четыре стиля покрывают подавляющее большинство того, с чем вы столкнётесь.

REST

REST (Representational State Transfer), доминирующий стиль в современном вебе. Это не столько строгий протокол, сколько набор соглашений: использовать стандартные HTTP-методы на понятно именованных эндпоинтах, делать каждый запрос самодостаточным и возвращать данные в простом формате вроде JSON. REST популярен благодаря доступности и отсутствию состояния: каждый запрос несёт всё необходимое серверу, и сервер не помнит предыдущих вызовов. Это делает REST API лёгкими для кэширования, масштабирования и изучения, именно поэтому большинство публичных API, которые вы встретите, являются RESTful.

SOAP

SOAP (Simple Object Access Protocol), более старый, строгий аналог. Там, где REST гибок, SOAP навязывает жёсткий контракт: сообщения всегда в XML и должны следовать формальной структуре. Эта строгость является преимуществом в регулируемых, высокорисковых средах. SOAP имеет встроенные стандарты безопасности, транзакций и надёжности, поэтому по-прежнему встречается в корпоративных средах, таких как банковское дело и обработка платежей, где гарантированная, проверяемая передача сообщений важнее удобства.

GraphQL

GraphQL, разработанный в Facebook в 2012 году, предлагает иной подход. Вместо множества эндпоинтов, каждый из которых возвращает фиксированную форму данных, он предоставляет единственный эндпоинт и позволяет клиенту запрашивать именно нужные поля. Преимущества следуют непосредственно из этого: вы перестаёте получать лишние данные, которые вам не нужны, можете получать связанные вещи в одном обмене вместо нескольких, а типизированная схема точно документирует, что доступно, ещё до отправки запроса. Эта точность делает GraphQL привлекательным для сложных приложений с множеством экранов, каждому из которых нужны слегка разные срезы одних и тех же данных.

Вебхуки

Вебхуки переворачивают привычное направление. С REST, SOAP и GraphQL ваше приложение спрашивает, а сервер отвечает; с вебхуком сервер сообщает вашему приложению в момент, когда что-то происходит, без какого-либо запроса с вашей стороны. Вы регистрируете URL, и когда происходит событие (платёж проходит, сборка завершается, форма отправляется) сервис отправляет запрос на ваш URL с деталями. Думайте об этом как о разнице между тем, чтобы периодически звонить на кухню и спрашивать, готов ли заказ, и кухней, которая просто звонит в колокольчик, когда готово. Вебхуки, стандартный способ получать обновления в реальном времени без постоянного опроса API.

Реальные примеры API

Чтобы определение API закрепилось, проще всего назвать несколько, которые вы почти наверняка использовали:

• Платежи. Когда страница оформления заказа списывает средства с вашей карты, в фоне вызывается API платёжного провайдера. Магазин никогда не касается сырых данных вашей карты; он просит API обработать транзакцию и ждёт ответа «одобрено» или «отклонено».
• Карты. Приложение доставки, показывающее живую карту и предполагаемое время прибытия, получает тайлы, маршруты и расстояния от картографического API, а не строит собственную карту мира.
• Вход через Google или Apple. Эти кнопки используют API аутентификации, чтобы приложение могло подтвердить вашу личность, так и не увидев ваш пароль.
• Погода. Прогноз в погодном приложении вашего телефона поступает от API погодного провайдера, те же данные продаются сельскому хозяйству, логистике и организаторам мероприятий.
• Социальные сети и стриминг. Публикация из стороннего приложения или получение персонализированного плейлиста проходит через API, которые читают и записывают данные от имени платформы.

Почему API имеют значение

API, причина того, что современное программное обеспечение создаётся из частей, а не с нуля. Ни одной команде не нужно писать собственный процессор платежей, картографический движок или систему аутентификации, когда хорошо задокументированный API выполняет задачу за несколько вызовов. Это позволяет компаниям быстрее выпускать продукты и сосредоточиться на том, что отличает их продукт, а не перестраивать уже решённые проблемы.

Они также создают реальную бизнес-ценность. API позволяют компании подключаться к партнёрским экосистемам, открывать новые каналы дистрибуции и достигать клиентских сегментов, которые иначе были бы недоступны. Многие организации теперь рассматривают свои данные и сервисы как самостоятельные продукты: погодная компания продаёт прогнозы через API, банк предоставляет данные аккаунтов финтех-приложениям, и оба превращают существующие системы в доход. API также унифицируют представление о клиенте, разрушая информационные силосы, чтобы приложение, сайт и чат-бот могли представлять одни и те же актуальные данные.

Когда у сайта нет API: скрейпинговый API

Вот в чём проблема. Немало нужных вам данных находится на публичном сайте, у которого вообще нет официального API. Информация прямо на странице, но нет ни чистого эндпоинта для вызова, ни ожидающего вас JSON. Традиционный ответ, веб-скрейпинг: загрузить HTML страницы и самостоятельно извлечь нужные значения. Это работает до тех пор, пока сайт не начнёт рендерить контент через JavaScript, блокировать незнакомых посетителей, выдавать CAPTCHA или менять макет, после чего простая загрузка превращается в постоянную проблему обслуживания.

Скрейпинговый API закрывает этот разрыв, оборачивая всё это за единственным эндпоинтом. Вместо самостоятельного управления браузерами, прокси и повторными попытками вы отправляете один запрос с указанием нужного URL и получаете страницу обратно как чистый ответ, точно тот же цикл запрос-ответ, что и в любом другом API. По сути, это даёт сайту без API API-подобный интерфейс: вы вызываете его так же, как погодный или платёжный сервис, а беспорядочные части загрузки реальной страницы остаются по другую сторону контракта.

Как только страница возвращается как предсказуемый ответ, применимо всё, что вы узнали выше. Вы можете разобрать HTML с помощью библиотеки, запросить данные с помощью Python или Node.js и передать результат в своё приложение точно так же, как если бы он пришёл из задокументированного JSON-эндпоинта. Сайт становится просто ещё одним API, который ваш код умеет вызывать.

Ответственный скрейпинг

Обращение с сайтом как с API не снимает с вас ответственности за то, как вы его используете. Придерживайтесь публичных данных, читайте и соблюдайте условия использования сайта и его robots.txt, честно идентифицируйте свои запросы и держите частоту запросов разумной, чтобы не перегружать чужие серверы. Управляемый скрейпинговый API помогает оставаться вежливым, распределяя и регулируя запросы за вас, но суждение о том, что собирать и насколько интенсивно работать с сайтом, по-прежнему остаётся за вами.

Часто задаваемые вопросы

Что такое API простыми словами?

API, это набор правил, позволяющих двум программам общаться между собой. Одна программа отправляет запрос с просьбой о данных или действии, а другая отправляет обратно ответ в согласованном формате. Как официант, несущий ваш заказ на кухню и приносящий еду обратно, API обрабатывает диалог, чтобы ни одна из сторон не знала, как другая устроена внутри.

В чём разница между API и сайтом?

Сайт создан для людей: он возвращает HTML, стилизованный для браузера, чтобы человек мог его прочитать. API создан для программ: он возвращает структурированные данные, обычно JSON, которые другое программное обеспечение может читать напрямую. Скрейпинговый API находится посередине, загружая страницу для людей и возвращая её как предсказуемый ответ, который ваш код может обработать.

Каковы основные типы API?

Наиболее распространённые стили: REST, SOAP, GraphQL и вебхуки. REST, гибкий, широко используемый стандарт для веб-сервисов. SOAP, более строгий XML-протокол, предпочтительный в корпоративной среде и финансовом секторе. GraphQL позволяет клиентам запрашивать именно нужные поля через один эндпоинт. Вебхуки обращают направление, позволяя серверу отправлять обновления в реальном времени в ваше приложение при наступлении события.

Что такое JSON и почему API его используют?

JSON (JavaScript Object Notation), лёгкий текстовый формат для представления данных в виде пар ключ-значение и списков. API предпочитают его, потому что он компактен, легко читается людьми и поддерживается каждым современным языком программирования, что делает ответы простыми для отправки, хранения и разбора.

Нужен ли ключ API для использования API?

Часто да. Многие API требуют ключ или токен, чтобы идентифицировать ваш аккаунт, контролировать доступ и отслеживать использование. Вы включаете ключ в каждый запрос, как предъявляете удостоверение у двери. Некоторые открытые API допускают ограниченное использование без ключа, но большинство продакшн-сервисов ожидают его наличия.

Как использовать сайт, у которого нет API?

Вы можете воспользоваться скрейпинговым API, который оборачивает сайт за единственным эндпоинтом. Вы отправляете запрос с указанием нужной страницы, и сервис загружает её, обрабатывая рендеринг, ротацию IP и блокировки за вас, затем возвращает HTML как чистый ответ. Далее вы разбираете данные точно так же, как из любого стандартного API.

TA

Thomas Adewale

Технический писатель · Crawlbase

Технический писатель в Crawlbase, освещает прокси-сети, стратегии ротации и внутреннее устройство надёжного краулинга в больших масштабах.