Что такое API и почему его называют интерфейсом
API описывает доступные операции, данные и правила обращения к ним. В библиотеке это могут быть функции, классы и свойства объектов. Человек работает с кнопками пользовательского интерфейса, а программист использует API в коде.
Представьте магазин с расчётом доставки. Покупатель выбирает город, магазин запрашивает варианты у перевозчика, затем показывает результат. Разработчику нужно знать параметры API и формат ответа. Разбираться во внутренних алгоритмах транспортной компании не требуется.
Для чего нужен API: примеры использования
API помогает программам взаимодействовать без ручного переноса данных. Можно использовать готовую функцию оплаты или доставки вместо разработки такой системы с нуля. Ниже учебные сценарии интеграции.
| Задача | Как может использоваться API | Что получает пользователь |
|---|---|---|
| Заказ онлайн | Магазин отправляет состав заказа в учётную систему | Сотрудник видит заказ без повторного ввода |
| Доставка | Приложение передаёт адрес и параметры отправления перевозчику | Покупатель выбирает подходящий способ получения |
| Платежи | Программа запрашивает состояние оплаты у платёжного сервиса | Статус заказа обновляется автоматически |
| Прогноз погоды | Мобильное приложение получает сведения о погоде для выбранного города | Температура появляется на экране |
| Остатки товаров | Учётная система передаёт доступное количество в каталог | Витрина показывает полученные сведения о наличии |
Как работает API: клиент, запрос и ответ
В сетевом API клиент отправляет запрос, сервер принимает его и готовит ответ. Обмен происходит по согласованному протоколу, например HTTP. Клиентом может быть сайт, мобильное приложение или программа учёта.
Адрес API, или конечная точка, указывает, куда отправить запрос. Метод HTTP задаёт операцию, заголовки передают служебную информацию. Параметры уточняют запрос, а тело сообщения содержит отправляемые данные, если они нужны.
Учебный запрос GET /api/products/book читает сведения о товаре book. Это условный путь, не действующий сервис. Ниже пример тела ответа в формате JSON. Поле name содержит название, in_stock сообщает о наличии. Приложение использует эти значения, чтобы показать товар на сайте.
- Приложение отправляет запрос к API по указанному адресу.
- Сервер проверяет параметры и право доступа, затем выполняет нужную функцию.
- API возвращает код состояния и данные. Клиент обновляет экран или показывает ошибку.
{
"name": "Книга",
"in_stock": true
}Какие бывают виды API
API библиотеки даёт доступ к функциям внутри программы. API операционной системы позволяет работать с файлами, памятью и устройствами. Браузерный API помогает менять страницу или обрабатывать звук. Сетевой API связывает приложения через сеть.
Название Web API зависит от контекста: так называют и интерфейсы веб-сервисов, и встроенные возможности браузера. API разных операционных систем могут различаться. Поэтому при переносе программы проверяют доступность нужных функций и при необходимости меняют код.
Компоненты могут образовывать слои: браузер использует API операционной системы, предоставляя сайту набор функций. Это упрощает взаимодействие, но верхний слой может открывать не все возможности нижнего.
Внутренние, партнёрские и публичные API
Внутренний API предназначен для систем одной организации. Партнёрский открывают согласованным участникам. Публичный предлагают внешним разработчикам на условиях поставщика.
Публичность не означает бесплатный доступ. Проверьте условия, разрешённые операции и порядок получения доступа. Открытая документация не даёт права читать чужие данные.
REST, SOAP, GraphQL и RPC
REST задаёт архитектурные ограничения. SOAP определяет правила обмена XML-сообщениями. GraphQL позволяет клиенту указать нужные поля ответа согласно схеме API.
RPC означает Remote Procedure Call, или удалённый вызов процедуры. Клиент обращается к функции на сервере через локальный метод. Например, gRPC описывает методы, входные сообщения и результаты в определении сервиса. Вызов выглядит привычно для программиста, но зависит от сети и может завершиться ошибкой.
При подключении чужого API подход выбирает поставщик. Для своего API сравнивайте требования к данным, клиентам и поддержке.
Вызов функции API: сигнатура и результат
Сигнатура помогает определить функцию и допустимый способ обращения к ней. Какие сведения входят в сигнатуру, зависит от языка программирования. Семантика описывает, что функция делает: какой результат возвращает и что меняет.
Представьте условную функцию deliveryCost(city, weight) для расчёта доставки. По документации city обозначает город, weight задаёт вес в согласованных единицах. Одного имени недостаточно: нужно знать допустимые значения, валюту результата и поведение при неизвестном городе.
API скрывает детали реализации за договорённостью. Разработчик может улучшить алгоритм, сохранив прежние параметры и смысл результата. Тогда вызывающему коду не нужны изменения. Но переименование поля или изменение его смысла может нарушить интеграцию: совместимость нужно проверять.
REST API: что это и как устроена архитектура
REST API это интерфейс, построенный с учётом принципов REST, Representational State Transfer. В центре подхода находится ресурс, например товар. Клиент получает его представление и выполняет разрешённые операции.
Принципы REST описал Рой Филдинг: разделение клиента и сервера, самодостаточность запросов, обозначение возможности кэширования, единый интерфейс и слои. Передача исполняемого кода клиенту необязательна.
Самодостаточный запрос содержит всё необходимое для обработки. Серверу не нужен контекст предыдущего обращения клиента. Это не запрещает хранить товары в базе данных.
Единый интерфейс включает адресацию ресурсов, работу через представления, самоописательные сообщения и ссылки на дальнейшие действия. Например, ответ о заказе может содержать ссылку на доступную отмену. Одного обмена JSON по HTTP недостаточно для соблюдения всех ограничений REST.
Методы HTTP в API: получение и изменение данных
Метод HTTP задаёт смысл запроса. В таблице приведены стандартные назначения; адреса и поля определяет документация конкретного API.
| Метод | Назначение | Условный пример |
|---|---|---|
| GET | Запросить представление ресурса | Прочитать карточку товара |
| POST | Передать данные для обработки по правилам ресурса | Создать заказ или отправить форму |
| PUT | Создать или заменить состояние целевого ресурса переданным представлением | Передать полное описание товара |
| PATCH | Применить частичные изменения | Изменить признак наличия |
| DELETE | Удалить связь ресурса с адресом; физическое стирание данных не гарантируется | Удалить карточку через предусмотренную операцию |
Почему повтор запроса требует внимания
POST не гарантирует идемпотентность. Если соединение оборвалось после создания заказа, повтор может создать ещё один заказ. Перед повторной отправкой проверьте предусмотренную поставщиком защиту от дублей. GET предназначен для чтения, хотя сервер может записывать обращение в журнал.
Форматы ответа API: JSON и XML
JSON описывает объекты, массивы, строки, числа, логические значения и null. Отдельного типа даты нет: способ её передачи согласуют разработчики. Формат связан с JavaScript, но используется в разных языках программирования.
XML записывает данные с помощью элементов и атрибутов. SOAP использует XML для оболочки сообщения. Заменить XML на JSON можно только при поддержке сервера. Названия полей и типы значений нужно сверять с документацией API.
Ключ API, авторизация и безопасность
Ключ API помогает сервису учитывать обращения приложения и управлять доступом. Он может быть секретом, дающим разрешение на операции. Поэтому считать его только счётчиком запросов опасно. Для защиты чувствительных данных одного ключа недостаточно.
Аутентификация подтверждает, кто обращается, а авторизация определяет разрешённые действия. Например, право читать каталог не должно автоматически давать право удалять товары. Проверять разрешения нужно на сервере при обращении к защищённой операции.
Передавайте секретные реквизиты через HTTPS способом, указанным в документации. Не помещайте их в URL: адрес может попасть в журналы. Секретный ключ храните на серверной стороне, не в коде страницы, доступном посетителю.
Лимит запросов ограничивает частоту обращений. При его превышении API может возвращать код 429. Учитывайте ограничения при проектировании обмена, а при утечке реквизитов отзывайте доступ. Эти меры описаны в рекомендациях OWASP по безопасности REST.
Как подключить API и что искать в документации
Начните с конкретного результата: какие сведения получать, куда передавать и кто отвечает за их правильность. Затем найдите официальную документацию API. Для первой проверки выберите безопасную операцию чтения, доступную вашему приложению.
Для собственного API определите методы и адреса, напишите обработчики и подключите нужные данные. Обработчик проверяет запрос, вызывает функцию приложения и формирует ответ. Опишите ошибки и порядок изменения интерфейса, затем проверьте обращения клиента.
- Проверьте адрес сервиса, описание метода, обязательные параметры и формат ответа.
- Уточните способ доступа и получите нужные разрешения у владельца системы.
- Сопоставьте поля: название товара, артикул, единицы измерения и значения статусов.
- Отправьте пробный запрос в предусмотренной поставщиком тестовой среде, если она есть.
- Проверьте успешный ответ, пустой результат, неверные параметры и отсутствие доступа.
- Определите обработку задержек, повторов, ограничений и изменений интерфейса.
Ошибки и ограничения при работе с API
Наличие API ещё не означает, что интеграция решит задачу целиком. Нужного поля может не быть, а операция может требовать дополнительных разрешений. До разработки проверьте сценарий от первого запроса до результата, который увидит пользователь.
- Не задано время ожидания: предусмотрите таймаут и понятное сообщение при задержке ответа.
- Нет проверки содержимого: убедитесь, что получены нужные поля и допустимые значения.
- Не учтены повторы: согласуйте защиту от повторного создания заказов.
- Устаревшие сведения показаны как актуальные: отмечайте время обновления сохранённых данных.
- Не назначен ответственный: определите, кто получает сообщения о сбоях и поддерживает интеграцию.
- Изменился API поставщика: проверяйте уведомления об обновлениях и совместимость полей до перехода на новую версию.
Когда бизнесу нужна интеграция API
Опишите повторяющуюся задачу: например, передачу заказов из магазина в учётную систему. Укажите направление обмена, нужные поля и действия при сбое. Это поможет оценить разработку и дальнейшую поддержку API.
API может быть и платным продуктом: поставщик продаёт доступ к данным или операциям, например по объёму обращений. До подключения уточните тариф, лимиты и условия использования результатов. Открытый API не означает бесплатную интеграцию.
Обсудить интеграцию можно через услугу «Разработка веб-приложений». seosite1 делает сайты с 2009 года, работает с 1С-Битрикс и 1С удалённо по России. Цена после брифа.