Что такое API простыми словами
↑ 1.1 Что такое API и как устроены системы · ← Предыдущая · → Следующая
Зачем это аналитику и PM
Пока API звучит как «тема разработчиков», требования описывают только экраны. Контракт запроса и ответа делает сценарий проверяемым: какие поля уходят, что считать успехом и какая ошибка допустима.
План темы
- аналогия с официантом и меню
- контракт между системами
- публичные, партнёрские и внутренние API
- зачем аналитику знать API
Объяснение
API (application programming interface, программный интерфейс) — набор операций, которыми одна программа пользуется в другой: что можно спросить или изменить, какие поля передать и какой ответ считать законным.
В кафе вы не заходите на кухню. Вы выбираете блюдо по меню и называете его официанту. Меню — список разрешённых заказов, официант приносит блюдо или отказ. API устроен так же.
Контракт между системами
Контракт можно проверить без устных пояснений. В нём есть операция, обязательные поля, смысл значений, пример успеха и пример отказа. Экран к контракту не относится: кнопку перерисовывают, не трогая API, и ломают интеграцию, не трогая макет.
Для одной операции в постановке хватает каркаса.
- Кто вызывает и зачем это в сценарии.
- Какие поля уходят.
- Что возвращается при успехе и какой факт после этого записан.
- Какой отказ видит человек.
- Что будет, если нажать действие дважды.
Публичные, партнёрские и внутренние
Открытость не равна протоколу. Публичный API отдают внешним разработчикам вместе с описанием. Партнёрский — конкретной компании по договору, часто с отдельной песочницей. Внутренний связывают свой экран и свои сервисы. Его тоже описывают, иначе каждая команда помнит свой набор полей.
| Вид | Кто вызывает | На что смотреть |
|---|---|---|
| Публичный | Внешние разработчики | Что обещано в документации и как предупреждают об изменениях |
| Партнёрский | Компания по договору | Песочница, тестовые данные, кто отвечает за сбой |
| Внутренний | Наши экраны и сервисы | Совпадает ли контракт с постановкой и кто владелец |
Зачем это аналитику
Аналитик переводит «клиент отменяет заказ» в вопросы контракта: до какого статуса можно, какие поля обязательны, что показать при отказе, уйдёт ли факт на склад. PM по тому же списку видит зависимость от другой команды. На приёмку кроме скриншота нужен пример запроса и ответа.
Примеры
Учебный JSONPlaceholder отдаёт запись без регистрации. Это чужой демонстрационный контракт, не ваш продукт.
curl -sS "https://jsonplaceholder.typicode.com/todos/1"{
"userId": 1,
"id": 1,
"title": "delectus aut autem",
"completed": false
}id отличает запись, completed — признак да или нет. Если поле исчезнет, клиенты сломаются, даже когда экран сервиса выглядит по-старому.
Схема своей операции для задачи. Это не ответ живого сервера. Хост в таких схемах не нужен: фиксируют поля.
{
"orderId": "1042",
"status": "cancelled",
"reason": "customer_request"
}Рядом пишут правило: отмена доступна, пока заказ не передан в доставку, повтор не создаёт вторую заявку.
Нюансы и подводные камни
- API есть не только у сайта. Им пользуются касса, банк, мобильное приложение. «Покажите API» без имени системы слишком широко.
- Адрес без полей, ошибок и владельца — ещё не контракт.
- Два экрана могут звать один метод, один экран — три. В требованиях полезны оба слоя.
- Ломает клиентов не только удаление метода. Смена смысла при том же имени поля тоже ломает: вчера статус 1 значил «создан», сегодня «оплачен».
Практика
Опишите одно действие («создать заявку» или «отменить заказ») как контракт, без макета.
Ожидаемый результат: есть имя операции, входные поля, пример успеха, два отказа (нет прав и нарушено правило) и фраза про повтор. Неизвестное помечено вопросом к команде, а не выдуманным значением.
Вопросы с ответами
API — это сервер?
Нет. Сервер выполняет работу. API — договорённость, как к этой работе обращаться. У одного сервера бывает несколько контрактов для разных клиентов.
Чем меню похоже на контракт?
Оно заранее ограничивает заказ и не пускает гостя на кухню. Пока меню не сменили, залу неважно, как переставили плиты.
Почему внутренний API тоже описывают?
Его вызывают другие ваши команды. Без описания экран и сервер расходятся в именах полей уже после макета.
Что такое ломающее изменение?
Старый клиент после него работает неправильно: поле исчезло, смысл значения сменился, появился новый обязательный атрибут. Новое необязательное поле мягче, но о нём всё равно говорят потребителям.