
Приложение доставки показывает карту, интернет-магазин получает статус оплаты, мобильный банк загружает баланс, а сайт авторизует пользователя через 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/125REST не означает просто 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/jsonAPI документация
Хорошая документация обычно описывает:
- адрес 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
- какой base URL используется;
- какая версия API актуальна;
- как устроена авторизация;
- какие rate limits действуют;
- какие HTTP-коды возвращаются;
- как работает пагинация;
- есть ли webhook;
- как хранить секреты;
- есть ли тестовая среда;
- что происходит при ошибках.
Итог
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 внешний сервис отправляет запрос на адрес клиента после наступления события, например после успешной оплаты.
































