Виды API: REST, SOAP, GraphQL, gRPC, вебхуки, очереди
↑ 1.1 Что такое API и как устроены системы · ← Предыдущая · → Следующая
Зачем это аналитику и PM
В одной интеграции команда говорит «REST», партнёр присылает XML, а оплата приходит отдельным вызовом на наш адрес. Если виды не различать, в срок попадает не тот объём работ и не те инструменты проверки.
План темы
- чем отличаются
- где что встречается
- как понять по документации, какой перед вами
Объяснение
Вид API — способ оформить один смысл «передать или запросить факт»: текстом по адресам, XML-конвертом, выбором полей, бинарным вызовом, обратным вызовом или сообщением в очередь.
Похоже на доставку документов. У REST отдельные ящики по делам. SOAP — бланк, где каждое поле стоит на своём месте. GraphQL — окно, куда приносят список «нужны только эти графы». gRPC — внутренняя почта, бланк которой читает специальный аппарат. Вебхук — курьер сам стучится, когда документ готов. Очередь — лоток «разберём, когда освободимся».
Чем отличаются и где встречаются
| Вид | Как устроен обмен | Где часто видят | Признак в документе |
|---|---|---|---|
| HTTP, его часто называют REST | Адрес на сущность, обычно JSON | Кабинеты, мобильные приложения, публичные API | Пути, GET и POST, примеры JSON |
| SOAP | XML-конверт и список операций | Банки, госсистемы, старые шины | WSDL, тела с тегами |
| GraphQL | Один адрес, клиент перечисляет поля | Экраны с разным составом данных | query, mutation, схема типов |
| gRPC | Вызов по бинарному контракту | Связь сервисов внутри компании | Файл .proto, слова rpc и protobuf |
| Вебхук | Чужая система вызывает наш адрес | Оплата, подпись, доставка | «Пришлём POST на ваш URL» |
| Очередь | Сообщение лежит, пока его не заберут | Письма, отчёты, пики заказов | Topic, queue, consumer |
REST в речи команды чаще значит «JSON по HTTP», а не строгий учебный стиль. SOAP описывают файлом WSDL, данные везут в XML. GraphQL отдаёт запрошенные поля, но отказ в доступе выглядит иначе, чем у обычного HTTP: это стоит спросить отдельно. gRPC неудобно читать глазами, для постановки берут имена методов и полей.
Вебхук и очередь — не другой формат тела, а другая сторона, которая начинает разговор. При вебхуке итог приходит позже на наш адрес. При очереди отправитель не знает, кто и когда прочитает сообщение.
Как узнать вид по бумаге
Смотрите на артефакт, не на заголовок слайда.
- Таблица адресов и JSON — HTTP, который назовут REST.
- WSDL и конверт XML — SOAP.
- Один вход и список полей в запросе — GraphQL.
- Файл
.proto— gRPC. - «Укажите ваш URL» — вебхук: наш сервер принимает чужой вызов.
- «Кладём событие, склад читает лоток» — очередь. Ответа в ту же секунду может не быть.
Один сценарий часто смешивает виды. Кабинет создаёт заказ по HTTP, склад читает очередь, партнёр бьёт вебхуком.
flowchart TD A["Есть описание интеграции"] --> B{"Кто начинает разговор"} B -->|"наш клиент сразу"| C{"Что лежит в документе"} B -->|"они зовут нас позже"| D["Вебхук"] B -->|"заберут когда смогут"| E["Очередь"] C -->|"адреса и JSON"| F["HTTP, часто зовут REST"] C -->|"WSDL и XML"| G["SOAP"] C -->|"список полей"| H["GraphQL"] C -->|"proto и rpc"| I["gRPC"]
Примеры
Учебный вызов JSONPlaceholder — JSON по HTTP, не SOAP и не очередь.
curl -sS "https://jsonplaceholder.typicode.com/posts/1"Ниже укороченный вид ответа: у живого сервиса поле body длиннее. Для узнавания вида достаточно того, что это объект JSON.
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit"
}Остальное — схемы для постановки, не ответы банков и не живой GraphQL.
query {
order(id: "1042") {
status
total
}
}Envelope
Body
CancelOrder
OrderId 1042{
"event": "payment.succeeded",
"orderId": "1042"
}У очереди такого ответа вызывающему может не быть. Тогда фиксируют имя события, поля сообщения и статус, который видит человек, пока лоток ещё не прочитали.
Нюансы и подводные камни
- Надпись REST не доказывает стиль. Проверяйте адреса и примеры. Иногда так называют один общий адрес на все операции.
- Клиент GraphQL не должен получать поле только потому, что умеет его назвать. Доступ спрашивают отдельно.
- Если обещают «документацию в Swagger», уточните, что это не внутренний gRPC без текстового описания.
- Вебхук требует доступный адрес, проверку отправителя и готовность получить то же событие дважды.
- Очередь не рисует экран «готово» в ту же секунду. Нужны статус «принято» и способ узнать итог.
Практика
Разложите три обмена: создание заказа, уведомление об оплате, письмо клиенту. Для каждого укажите вид и кто начинает разговор.
Ожидаемый результат: у строки есть подтверждение из документа (адрес и JSON, WSDL, «пришлём на URL» или имя очереди). Если подтверждения нет, стоит вопрос владельцу, а не ярлык «REST» наугад.
Вопросы с ответами
Почему фразы «сделайте REST» мало?
Так часто называют любой JSON по HTTP. Для срока важнее, кто кого вызывает и нужен ли итог сразу.
Чем вебхук отличается от запроса нашего экрана?
Экран сам ждёт ответ. Вебхук начинает партнёр, когда событие уже случилось, и зовёт наш адрес. Нужны задержка и повтор.
Когда уместна очередь?
Когда работу можно закончить позже: письмо, тяжёлый отчёт, склад в пик. Человеку показывают «принято». Если без итога нельзя идти дальше по экрану, одной очереди мало.
Как отличить SOAP от JSON API?
У SOAP ищут WSDL и XML, у JSON API — пути и примеры объектов. Заголовок «веб-сервис» бывает у обоих.