Сегодня покупают

Что такое API: как приложения обмениваются данными

Что такое API: как приложения обмениваются данными

Приложение доставки показывает карту, интернет-магазин получает статус оплаты, мобильный банк загружает баланс, а сайт авторизует пользователя через Google. Во всех этих случаях программы должны обмениваться данными между собой. Для этого часто используется API.

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

Разберём, что такое API простыми словами, как приложения отправляют запросы и получают ответы, что такое REST, endpoint, JSON, API-ключи и HTTP-коды, а также покажем, как выглядит типичный обмен данными между сайтом, мобильным приложением и сервером.

Программы и инструменты для работы с компьютером представлены в разделе программного обеспечения AplTech.kz. Для разработки также можно подобрать ноутбук.

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

API расшифровывается как Application Programming Interface, то есть программный интерфейс приложения.

Проще всего представить API как набор правил:

какой запрос можно отправить
+
куда его отправить
+
какие данные передать
+
какой ответ ожидать

Если программа соблюдает эти правила, она может использовать функции другого сервиса.

Пример без программирования

Допустим, мобильное приложение погоды должно показать температуру в Алматы.

Само приложение не устанавливает метеостанции по всему городу. Вместо этого оно обращается к сервису погоды через API.

Приложение
↓
API-запрос
↓
Сервис погоды
↓
API-ответ
↓
Температура отображается пользователю

Приложению не нужно знать, откуда именно сервис получил данные. Для него важен только формат API.

API и интерфейс пользователя - разные вещи

Обычный пользователь взаимодействует с программой через UI:

  • кнопки;
  • формы;
  • меню;
  • экран приложения.

Другая программа взаимодействует с сервисом через API.

Например:

Человек → нажимает кнопку "Показать заказы"

Приложение → отправляет API-запрос серверу

Клиент и сервер

В типичной схеме есть две стороны.

Клиент отправляет запрос.

Сервер принимает его, выполняет действие и возвращает ответ.

Клиент
   ↓ запрос
Сервер
   ↓ ответ
Клиент

Клиентом может быть:

  • сайт;
  • мобильное приложение;
  • настольная программа;
  • другой сервер;
  • скрипт;
  • бот.

Что такое endpoint

Endpoint - это конкретный адрес API, отвечающий за определённую функцию.

Например:

https://api.example.com/users

может возвращать пользователей, а:

https://api.example.com/orders

работать с заказами.

Один API может иметь много endpoint

Например, API интернет-магазина:

/products
/categories
/cart
/orders
/customers
/payments

Каждый endpoint предназначен для своей части системы.

Что такое API-запрос

Запрос обычно содержит несколько элементов:

  • URL;
  • HTTP-метод;
  • заголовки;
  • параметры;
  • тело запроса;
  • данные авторизации.

HTTP-методы

В веб-API часто используются стандартные HTTP-методы.

МетодТипичная задача
GETПолучить данные
POSTСоздать объект или отправить данные
PUTПолностью обновить объект
PATCHИзменить часть объекта
DELETEУдалить объект

Пример GET-запроса

Приложение хочет получить информацию о товаре:

GET /products/125

Сервер находит товар с ID 125 и возвращает его данные.

Пример POST-запроса

Пользователь оформляет заказ.

Приложение может отправить:

POST /orders

и передать внутри данные заказа.

Что такое JSON

JSON - один из самых распространённых форматов передачи данных через API.

Пример:

{
  "id": 125,
  "name": "Ноутбук",
  "price": 399990,
  "available": true
}

Такой формат удобно читать и человеку, и программе.

JSON не является API

API определяет правила взаимодействия.

JSON является только форматом данных.

API также может использовать:

  • XML;
  • Protocol Buffers;
  • обычный текст;
  • двоичные данные;
  • другие форматы.

Как выглядит полный обмен

Пользователь открывает карточку товара.

1. Браузер открывает страницу
2. JavaScript отправляет GET /products/125
3. Сервер проверяет запрос
4. Сервер получает данные из базы
5. API возвращает JSON
6. Сайт показывает название, цену и наличие

Что такое REST API

REST - один из наиболее распространённых подходов к созданию веб-API.

В REST обычно используются:

  • HTTP;
  • URL для ресурсов;
  • GET, POST, PUT, PATCH, DELETE;
  • коды HTTP-ответов;
  • часто JSON.

Например:

GET    /products
GET    /products/125
POST   /products
PATCH  /products/125
DELETE /products/125

REST не означает просто JSON через HTTP

REST содержит архитектурные принципы, связанные с ресурсами, состоянием запросов и взаимодействием клиента с сервером.

На практике термин REST API часто используют шире для HTTP API с ресурсными URL и стандартными методами.

HTTP-коды ответа

API сообщает не только данные, но и результат выполнения запроса.

КодЧто обычно означает
200Запрос выполнен успешно
201Объект создан
204Успешно, но тела ответа нет
400Ошибка в запросе
401Не выполнена авторизация
403Доступ запрещён
404Ресурс не найден
429Слишком много запросов
500Внутренняя ошибка сервера
503Сервис временно недоступен

401 и 403 - не одно и то же

Упрощённо:

401 → сервер не может подтвердить вашу авторизацию

403 → сервер понял, кто вы, но не разрешает действие

Реальное поведение конкретного API всегда нужно проверять по документации.

Как API понимает, кто отправил запрос

Используются разные способы авторизации:

  • API Key;
  • Bearer Token;
  • OAuth 2.0;
  • JWT;
  • сессионные cookies;
  • клиентские сертификаты.

Что такое API Key

API-ключ представляет собой уникальный секрет, который сервис выдаёт приложению или разработчику.

Например:

X-API-Key: abc123...

Сервер проверяет ключ и понимает, какому клиенту разрешён доступ.

API-ключ нельзя публиковать

Секретные ключи нельзя:

  • вставлять в открытый GitHub-репозиторий;
  • показывать в HTML страницы;
  • отправлять в публичных сообщениях;
  • хранить в мобильном приложении как надёжно защищённый секрет.

Если ключ доступен пользователю в клиентском коде, его в большинстве случаев можно извлечь.

Что такое Bearer Token

Токен часто передаётся в HTTP-заголовке:

Authorization: Bearer TOKEN

Он может представлять конкретного пользователя или приложение и иметь ограниченный срок действия.

OAuth 2.0

OAuth используется, когда одно приложение получает ограниченный доступ к другому сервису без передачи основного пароля пользователя.

Типичный пример:

"Войти через Google"
"Войти через Microsoft"

Пользователь подтверждает доступ, после чего приложение получает токен.

Почему не стоит передавать пароль стороннему приложению

Современные API стараются использовать токены и отдельные механизмы авторизации.

Это позволяет:

  • ограничивать права;
  • отзывать доступ;
  • задавать срок действия;
  • не раскрывать основной пароль.

Что такое параметры запроса

Дополнительные данные могут передаваться прямо в URL.

Например:

GET /products?category=laptops&page=2

Здесь:

category=laptops
page=2

являются query parameters.

Path parameter

Идентификатор объекта часто находится непосредственно в пути:

GET /users/42

Здесь 42 обозначает конкретного пользователя.

Тело запроса

При POST, PUT или PATCH данные часто передаются в body.

Например:

{
  "name": "Иван",
  "email": "user@example.com"
}

Что такое headers

HTTP-заголовки передают служебную информацию.

Например:

Content-Type: application/json
Authorization: Bearer ...
Accept: application/json

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

Хорошая документация обычно описывает:

  • адрес API;
  • endpoint;
  • методы;
  • параметры;
  • формат запросов;
  • формат ответов;
  • авторизацию;
  • ошибки;
  • ограничения.

Почему нельзя угадывать API

Даже если два сервиса используют REST, структура может быть совершенно разной.

Например:

/users/25

/client/25

/customer?id=25

могут решать похожую задачу в разных системах.

Поэтому ориентироваться нужно на документацию конкретного API.

Что такое Swagger и OpenAPI

OpenAPI позволяет формально описывать HTTP API.

На основе такого описания можно автоматически создавать:

  • интерактивную документацию;
  • список endpoint;
  • схемы данных;
  • примеры запросов;
  • часть клиентского кода.

Swagger часто используется как набор инструментов вокруг OpenAPI.

Что такое SDK

SDK - набор готовых инструментов разработчика.

Вместо ручной отправки HTTP-запроса разработчик может вызвать готовый метод.

Например, условно:

client.getProduct(125)

SDK самостоятельно сформирует нужный API-запрос.

API и SDK - не одно и то же

API определяет, как обращаться к сервису.

SDK предоставляет готовые библиотеки и инструменты, которые упрощают такое обращение.

Что такое rate limit

Сервисы часто ограничивают количество запросов.

Например:

100 запросов в минуту

Это защищает систему от:

  • перегрузки;
  • ошибочных циклов;
  • автоматизированных атак;
  • слишком большого использования бесплатного тарифа.

Ошибка 429

HTTP 429 Too Many Requests обычно означает, что клиент превысил допустимую частоту обращений.

Приложение должно учитывать ограничения и повторять запрос через предусмотренный интервал.

Пагинация

API редко возвращает миллион объектов одним ответом.

Данные делятся на страницы.

Например:

/products?page=1&limit=50
/products?page=2&limit=50

Зачем нужна пагинация

Она уменьшает:

  • размер ответа;
  • нагрузку на сервер;
  • потребление памяти;
  • время ожидания.

Что такое webhook

Обычный API-запрос работает по принципу:

клиент спрашивает
↓
сервер отвечает

Webhook позволяет серверу самостоятельно отправить уведомление, когда произошло событие.

Пример webhook при оплате

Покупатель оплатил заказ
↓
платёжный сервис
↓
Webhook
↓
интернет-магазин
↓
заказ получает статус "Оплачен"

Магазину не нужно каждую секунду спрашивать платёжный сервис, прошла ли оплата.

Webhook тоже является HTTP-запросом

Разница заключается в инициаторе.

При обычном API приложение обращается к сервису.

При webhook внешний сервис обращается к заранее указанному адресу приложения.

Что такое GraphQL

GraphQL является другим подходом к API.

Клиент может явно указать, какие поля ему нужны.

Условный запрос:

product {
  name
  price
  stock
}

Сервер вернёт только запрошенную структуру.

REST или GraphQL

Нельзя сказать, что один вариант всегда лучше.

REST:

  • прост;
  • широко распространён;
  • хорошо работает с HTTP;
  • имеет понятную модель ресурсов.

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

Что такое API базы данных

Мобильное приложение обычно не должно подключаться напрямую к основной базе компании.

Правильнее использовать:

Приложение
↓
API
↓
Backend
↓
Database

Сервер проверяет права пользователя и только после этого выполняет операции с базой.

Почему нельзя давать приложению прямой доступ к базе

Это создаёт серьёзные проблемы:

  • учётные данные приходится хранить у клиента;
  • сложно контролировать права;
  • невозможно надёжно проверить бизнес-логику;
  • структура базы становится доступна извне.

API интернет-магазина

В интернет-магазине через API могут взаимодействовать:

  • сайт;
  • мобильное приложение;
  • CRM;
  • ERP;
  • склад;
  • служба доставки;
  • платёжная система;
  • система аналитики.

Пример оформления заказа

Сайт
↓
API магазина
↓
создание заказа
↓
API оплаты
↓
оплата
↓
webhook
↓
статус заказа изменён
↓
API доставки
↓
создана отправка

API может быть публичным и внутренним

Public API предоставляется внешним разработчикам.

Private API используется только внутри компании.

Partner API может предоставляться ограниченному кругу партнёров.

Версии API

Со временем структура может меняться.

Поэтому встречаются адреса:

/api/v1/products
/api/v2/products

Старая версия может некоторое время продолжать работать, пока клиенты переходят на новую.

Почему API может перестать работать

Причины:

  • сервис недоступен;
  • истёк токен;
  • изменился endpoint;
  • превышен rate limit;
  • отключена старая версия API;
  • неверно отправлены данные;
  • изменились права пользователя.

Приложение должно обрабатывать ошибки

Плохая реализация:

API не ответил
↓
приложение зависло

Хорошая реализация:

API не ответил
↓
тайм-аут
↓
повторная попытка при необходимости
↓
понятное сообщение пользователю

Что такое timeout

Клиент не должен ждать ответ бесконечно.

Если сервер долго не отвечает, запрос завершается по тайм-ауту.

Дальше программа решает:

  • повторить запрос;
  • показать ошибку;
  • использовать кэш;
  • перейти в offline-режим.

Что такое кэширование API

Некоторые данные не нужно запрашивать каждую секунду.

Например, каталог категорий можно временно сохранить.

Это снижает:

  • нагрузку;
  • количество запросов;
  • задержку;
  • расход трафика.

API и HTTPS

Внешние API следует использовать через защищённое соединение HTTPS.

Оно шифрует передаваемые данные между клиентом и сервером.

Особенно это важно для:

  • токенов;
  • персональных данных;
  • платёжной информации;
  • учётных записей.

Что проверить разработчику перед использованием API

  1. какой base URL используется;
  2. какая версия API актуальна;
  3. как устроена авторизация;
  4. какие rate limits действуют;
  5. какие HTTP-коды возвращаются;
  6. как работает пагинация;
  7. есть ли webhook;
  8. как хранить секреты;
  9. есть ли тестовая среда;
  10. что происходит при ошибках.

Итог

API - это набор правил, по которым одна программа взаимодействует с другой. Клиент отправляет запрос на определённый endpoint, сервер выполняет действие и возвращает данные или информацию о результате.

В веб-разработке API часто работает через HTTP. Для получения данных используется GET, для создания POST, для изменения PUT или PATCH, а для удаления DELETE. Информация часто передаётся в формате JSON.

REST является распространённым способом организации веб-API, но существуют и другие подходы, например GraphQL. Для уведомлений о событиях применяются webhooks, а для упрощения работы разработчика сервис может предоставлять SDK.

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

Частые вопросы об API

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

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

Что такое REST API?

REST API обычно организует работу вокруг ресурсов и использует стандартные возможности HTTP, включая URL, методы GET, POST, PUT, PATCH и DELETE, а также HTTP-коды ответа.

Что такое endpoint в API?

Endpoint - это конкретный адрес API для определённой операции или ресурса. Например, один endpoint может возвращать товары, а другой работать с заказами.

Почему API часто использует JSON?

JSON имеет простую текстовую структуру, хорошо поддерживается языками программирования и подходит для передачи объектов, списков, строк, чисел и логических значений.

Что означает ошибка API 401?

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

Что такое API-ключ?

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

Чем webhook отличается от API-запроса?

При обычном API-запросе клиент сам обращается к сервису. При webhook внешний сервис отправляет запрос на адрес клиента после наступления события, например после успешной оплаты.

Читать также