API та інтеграції

Що охоплює ця категорія

Тут зібрано чотири споріднені завдання. Створення й тестування запитів вручну. Документування інтерфейсу, щоб ним могли користуватися інші. Шлюз перед кількома сервісами, щоб ключі, ліміти запитів, квоти й версії поводилися всюди однаково. Переміщення даних між продуктами, які ніколи не проєктували для спілкування.

Перші три призначені для команд, що випускають API. Четверте для тих, хто зшиває куплені інструменти. Обидві аудиторії потрапляють в одну категорію, тому продукти й виглядають такими різними.

Суто візуальна автоматизація без коду належить до no-code і автоматизації. Сповіщення про стан живого сервісу це моніторинг.

Клієнти і чим вони тепер відрізняються

Кожен клієнт надсилає запит і показує відповідь. Відмінності сховані глибше.

Спочатку обробка середовищ: локальне, тестове, робоче й те, що колега запускає на ноутбуці, з чистим перемиканням без ручного редагування URL. Потім скриптування, щоб токен можна було отримати перед запитом, а не вставляти щоранку. Потім перевірочні твердження в тестах, щоб колекцію міг запускати сервер збірки.

У співпраці думки розходяться. Хмарна синхронізація зручна, але історія ваших запитів лежить на чужих серверах. Файлові інструменти тримають колекції в репозиторії поруч із кодом, тож зміну переглядають як будь-яку іншу, і жоден робочий простір не йде разом зі співробітником, що звільняється.

Так чи так, питайте, де лежать секрети. Ключ, записаний в експортовану колекцію, це типовий шлях до публічного репозиторію.

Документація, що не псується

Рукописна документація застаріває за квартал. Єдине, що виживає, це генерація зі специфікації, яка живе разом із кодом і перебудовується під час злиття коду.

Перевірте три речі: чи продукт читає формат вашої специфікації без кроку конвертації, чи можна виконувати приклади зі сторінки і чи залишаються опублікованими старі версії для тих, хто ще ними користується.

Журнал змін важливіший за дизайн. Споживачам треба знати, що зламалося і коли, і жодне оформлення цього не замінить.

Шлюзи і коли вони виправдані

Одному сервісу шлюз рідко потрібен. Потреба виникає, коли автентифікація, ліміти запитів, квоти й версіонування мають поводитися однаково в кількох сервісах.

Тоді питання такі: де він працює і яку затримку додає, як визначаються ліміти і що бачить абонент, коли його досягнуто, чи можна міняти ключі без простою та що містять журнали. Усе, що завершує трафік, саме стає ризиком доступності, тож спитайте, що буде, коли у самого шлюзу поганий день.

Що міряють ціни

• Місця в клієнтах і продуктах документації, іноді безкоштовні для рецензентів лише з читанням.
• Завдання чи запуски на платформах інтеграцій, що рахуються за кроком, а не за процесом.
• Виклики чи трафік на шлюзах, з окремою ставкою для всього кешованого.
• Зберігання історії запусків, яке коротке на початкових тарифах і коротке саме тоді, коли воно потрібне.
• Конектори, де преміальні відкладено на тариф вище за той, що вам назвали.

Ціну за завдання варто порахувати до підпису. Процес із шістьма кроками, що запускається кожні десять хвилин, це не одне завдання на місяць, і число, в яке він перетворюється, здивувало чимало команд. Такі самі сюрпризи в інших категоріях зібрано в матеріалі що приховують сторінки з цінами.

Що перевірити

Відтворіть від початку до кінця одну реальну інтеграцію, яка у вас уже працює, разом із тим місцем, де інший бік повертає помилку.

Подивіться, як інструмент поводиться з повторними спробами, дубльованою доставкою, завислою третьою стороною та даними, що прийшли без одного поля. Добре зроблені продукти дозволяють повторити невдалий запуск після усунення причини. Слабші втрачають його мовчки й нічого не кажуть, поки не скаже клієнт.

Потім перевірте вихід. Колекції, специфікації й визначення процесів мають експортуватися у файли, які можна прочитати. Усе, що замкнено всередині робочого простору, це робота, яку ви виконаєте двічі.

Документація, версії і збереження споживачів

Інтерфейс із користувачами це обіцянка, і більша частина труднощів у цій категорії походить зі зміни такого інтерфейсу без порушення обіцянки.

Визначте підхід до версіонування до приходу першого зовнішнього споживача, бо запізніле впровадження означає просити всіх змінитися одночасно. Яка б не була схема, публікуйте, що змінилося і коли, і давайте період припинення підтримки, який вимірюється місяцями, а не тижнями.

Помилки заслуговують на таку саму увагу, як і успіхи. Відповідь, що каже, що пішло не так, яке поле стало причиною і що робити далі, знімає більше звернень до підтримки, ніж будь-яка кількість прози.

Потім прочитайте власну документацію очима новачка. Найшвидше покращення зазвичай це робочий приклад угорі сторінки замість довідкової таблиці.