API - узгоджений спосіб однієї програми запросити дані або дію в іншої. Завдяки йому сайт передає заявку до CRM, платіжний сервіс повідомляє результат, а мобільний застосунок показує баланс. Корисний API - не просто набір адрес. Це домовленість про структуру даних, права доступу, помилки та зміни.
Виходьте з реальних дій
Почніть із подій і записів, потрібних інтеграції. Дайте операціям зрозумілі назви та повертайте клієнту лише необхідні дані. Опишіть допустимі вхідні дані, можливі відповіді й помилки. Документація та приклади мають відповідати робочій версії сервісу, а не старій ідеальній схемі.
Безпека - частина домовленості
Перевіряйте, хто надіслав запит і чи дозволено йому конкретну дію з конкретним записом. Самої загальної ролі користувача недостатньо. Обмежуйте частоту запитів і перевіряйте всі вхідні дані. Секретні токени тримайте на довіреному сервері, а зміни грошей, прав і клієнтських даних записуйте в журнал.
Враховуйте ненадійну мережу
Запит може завершитися за тайм-аутом уже після того, як інший сервіс виконав дію. Важливі операції запису мають бути ідемпотентними: повтор не повинен створювати друге замовлення чи платіж. Визначте тайм-аути та зрозумілі правила повторення. Для інтеграцій на подіях зберігайте спроби доставки й передбачте повтор невдалих подій.
Плануйте зміни
Клієнти й сервери рідко оновлюються одночасно. За можливості вносьте сумісні зміни, а несумісні - випускайте в новій версії API. Стежте, хто ще використовує стару поведінку. Добре підтримуваний API дає змогу розвивати продукт без крихких індивідуальних виправлень для кожної інтеграції.
