Интеграции: API

Что такое API?

API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так, я обязуюсь делать это». API содержит набор функций, классов и методов, с помощью которых программы могут взаимодействовать между собой.

API включает:

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

При чем тут интерфейс?

В программировании контракт — это и есть интерфейс. В классическом описании ООП есть 3 кита:

Инкапсуляция
Наследование
Полиморфизм

Инкапсуляция — это скрытие реализации. Для пользователя все легко и понятно. Нажал на кнопочку — получил отчет. А как это работает изнутри — ему все равно. Какая база данных скрыта под капотом? Oracle? MySQL? На каком языке программирования написана программа? Как именно организован код? Не суть. Программа предоставляет интерфейс, им он и пользуется.

Не всегда программа предоставляет именно графический интерфейс. Это может быть SOAP, REST интерфейс, или другое API.

Пользователи работают с GUI — graphical user interface. Программы работают с API — Application programming interface. Им не нужна графика, только контракт.

Примеры API

API сервисов Ensi

Например, рассмотрим метод API сервиса OMS для получения статуса оплаты конкретного заказа:

У метода есть обязательный параметр - id заказа, статус оплаты которого мы хотим запросить:

Например, для заказа с id = 1 будет сформирован запрос 'GET' \ 'https://master_oms.ensi-api-docs-demo.greensight.ru/api/v1/orders/orders/1:check-payment'

В случае успеха в ответе будет получен код 200 и данные, содержащие статус оплаты заказа в формате JSON. В случае ошибки, будет получен код ошибки (в данном случае 404 или 500) и его описание.

Подходы Code first и Contract first

Разрабатывая сервис, такой как REST API или SOAP API, можно выбрать один из двух подходов:

Code First
Contract First

При подходе Code First контракт генерируется из кода при помощи, например, Swagger.

В случае Contract First уже код разрабатывается на основе контракта.

В Ensi принят подход Contract First, а в качестве архитектурного стиля используется REST.

Требования к контрактам

При спецификации требований к контрактам аналитик должен проработать:

список запросов, их форматы и параметры запросов;
форматы ответов, в том числе возможные ошибки с кодами.

Контракты должны быть спроектированы согласно API Design Guide

При использовании внешних контрактов, в документации обязательно должны быть зафиксированы:

адрес ресурса (url), в том числе, если есть, тестового;
токен для авторизации, его источник и частота обновления.

Дополнительно для описания интеграций могут быть полезны:

DFD (data flow diagram);
таблицы меппинга данных (для требований по записи/извлечению данных в/из БД).

Дополнительные материалы