Виды API: открытые, партнёрские и внутренние

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

По доступу

Внутренние API

Используются только внутри компании: связывают сайт с учётом, мобильное приложение с сервером, бота с CRM. Снаружи недоступны или закрыты строгой авторизацией. Можно менять быстрее, потому что все потребители под контролем. Ошибка — думать, что внутреннему API защита не нужна: доступ к нему должен быть ограничен так же строго.

Партнёрские API

Открываются конкретным партнёрам по договорённости: поставщику для передачи остатков, службе доставки для статусов, дилерам для заказов. Требуют документации, отдельных ключей для каждого партнёра, ограничений прав и частоты запросов. Изменения нужно согласовывать, потому что партнёры встроили API в свои системы.

Открытые (публичные) API

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

Композитные API

Один запрос объединяет обращения к нескольким сервисам. Например, мобильному приложению нужен экран заказа: данные заказа, статус доставки и бонусы клиента. Вместо трёх запросов приложение делает один к промежуточному слою, а тот собирает ответ. Это ускоряет работу приложения на медленном мобильном интернете.

По технологии

REST

Самый распространённый стиль веб-API: ресурсы с адресами, методы HTTP, данные в JSON. Прост в использовании и поддерживается любыми инструментами. Подходит для большинства бизнес-интеграций.

SOAP

Более старый протокол с сообщениями в XML и строгой схемой. Встречается в банковских, государственных и корпоративных системах. Тяжеловеснее REST, но формален и хорошо описан.

GraphQL

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

gRPC

Быстрый обмен между внутренними сервисами по строгим контрактам в двоичном формате. Для внешних партнёров используется реже.

Вебхуки

Обратное направление: не вы спрашиваете сервис, а он сам отправляет вам запрос при событии — оплата прошла, заказ доставлен, клиент написал боту.

Библиотечные и системные API

Интерфейсы программ и операционных систем, которые вызываются не по сети, а внутри приложения. Для бизнес-задач встречаются, например, при работе с оборудованием: кассой, весами, сканером.

Как выбрать вид для своей задачи

• Связываете свои системы — внутренний REST API с авторизацией
• Даёте доступ поставщикам и дилерам — партнёрский API с ключами, правами и документацией
• Хотите, чтобы сторонние разработчики строили сервисы на ваших данных — публичный API как отдельный продукт
• Нужно узнавать о событиях сразу — вебхуки вместо постоянных опросов
• Интегрируетесь с готовой системой — используете то, что она предлагает

Что нужно любому API, открытому наружу

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

Частые ошибки

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

Итог

Для заказчика главный вопрос — кто будет пользоваться API и какие данные ему можно видеть. Технология вторична и обычно выбирается командой под задачу.