Разработка
API: какие правила нужны для обмена данными между системами
Программный интерфейс: набор доступных операций и правил, по которым одна программа взаимодействует с другой программой или её частью.
Редакция:
В проекте сайта API часто обсуждают как способ получить данные из каталога, передать заявку или запросить состояние заказа. Понятие шире обмена через интернет: программные интерфейсы есть также у браузера и библиотек. Это отражено в определении MDN.
Для заказчика API полезно воспринимать как технический контракт: какие действия доступны, что нужно передать и что означает ответ. Здесь слово «контракт» описывает правила обмена, а не заменяет договор на разработку.
Пример: создание обращения
Учебная ситуация: сайт передаёт в CRM контакт, описание запроса и источник перехода. В API могут существовать операции создания и поиска обращения, но доступные поля и права различаются. Подрядчику нужны актуальная документация, разрешённый доступ и проверка нужной операции в согласованной среде.
Фраза «у CRM есть API» не подтверждает, что в вашем варианте подключения можно создать нужную сущность, заполнить все поля и найти результат. Даже совпадающие названия полей могут означать разные данные.
Что согласовать до разработки
| Часть правил | Вопрос для проекта |
|---|---|
| Операция | Что именно делает запрос: читает, создаёт или изменяет данные? |
| Данные | Какие поля обязательны, какие значения допустимы и как связываются записи? |
| Доступ | Кто может выполнить действие и как отзывается доступ? |
| Ответ | Что означает принятие, завершение или отказ; как найти результат? |
| Ограничения | Какие лимиты, версии и правила изменения интерфейса нужно учитывать? |
| Повтор | Как повторить запрос после неопределённого результата без нежелательного дубля? |
Не предполагается, что любой API уже предоставляет все удобные механизмы. Если нет возможности безопасного повтора или нужного поля, это ограничение влияет на проектирование и оценку работы.
Как проверить результат
Проведите согласованный тест: отправьте допустимые данные, найдите соответствующую запись у получателя и сверьте поля. Затем проверьте отказ для ошибочных данных и поведение при предусмотренном сбое. Сохраняйте безопасный идентификатор проверки; секреты доступа не включайте в публичный отчёт.
Положительный HTTP-ответ может означать только принятие запроса, если так определены правила системы. Для фоновой обработки нужен отдельный способ узнать итог. Подробности серверной части разобраны в термине backend.
API и уведомления по событию
При обычном запросе инициатор сам обращается за данными или действием. Webhook позволяет другой системе уведомить получателя о событии через заранее настроенный адрес. Эти способы могут использоваться вместе: уведомление сообщает об изменении, а запрос получает актуальные сведения.
В плане интеграций сайта зафиксируйте операции, поля, источник истины, ограничения и доказательство завершения. Готовность интеграции оценивается по согласованному сценарию целиком, а не по одному адресу API.