Що таке веб-сервіс та їх види?

Вебсервіс — програмний інтерфейс, через який застосунки обмінюються даними мережею, зазвичай через HTTP або HTTPS. Слово «сервіс» уживають і ширше щодо онлайн-інструментів, але вебсервіс як інтерфейс відрізняється від звичайної сторінки для людини.

Як взаємодіють застосунки

Клієнт надсилає запит на адресу інтерфейсу, а сервер повертає відповідь в узгодженому форматі, наприклад JSON. API визначає доступні операції, параметри, авторизацію та можливі помилки. Саме використання HTTP не перетворює довільний сайт на API: інтерфейс повинен мати зрозумілий контракт для програми-клієнта.

Поширені підходи

HTTP API часто проєктують навколо ресурсів і стандартних методів GET, POST, PUT або DELETE. GraphQL задає мову запитів і схему даних. SOAP — протокол обміну структурованими повідомленнями. Ці підходи розв’язують різні завдання; вибір залежить від вимог до даних, сумісності та керування доступом. FTP, SSH і Telnet — окремі мережеві протоколи, а не різновиди вебсервісів.

На що звертати увагу користувачу API

Перевіряйте чинну документацію, обмеження частоти запитів, способи автентифікації та обробку помилок. Не передавайте секрети в публічному URL і використовуйте HTTPS для конфіденційних даних. Практичний приклад програмного інтерфейсу — 2IP API; доступність конкретних методів слід звіряти з його актуальною документацією.

Інтерфейс і контракт сервісу

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

Документацію можна написати вручну або подати як опис, який обробляє програма, наприклад OpenAPI для HTTP API. У будь-якому разі приклади мають відповідати робочій версії сервісу. Адреси кінцевої точки без опису вхідних даних і помилок замало для надійної інтеграції. Вебсервіс може працювати всередині організації й не бути відкритим у публічному інтернеті.

Методи HTTP та зміст відповіді

Метод GET призначений для отримання представлення ресурсу й має бути безпечним у значенні відсутності запитаної клієнтом зміни стану. POST передає дані на обробку; PUT зазвичай замінює стан указаного ресурсу, а DELETE запитує видалення. Конкретна семантика залежить від API, але стандартні методи й коди відповіді допомагають клієнтові уникнути хибних припущень.

Код 200 повідомляє про успішну обробку конкретного HTTP-запиту, 201 — про створення ресурсу, 400 — про проблему із запитом, 401 — про потребу автентифікації, 403 — про відмову в доступі, 404 — про відсутність вибраного ресурсу, 429 — про обмеження частоти. Не варто вважати кожну помилку 500 доказом несправності мережі: з’єднання могло бути успішним, а проблема виникла в застосунку. Семантику описано в RFC 9110.

Формат даних і сумісність

JSON поширений у HTTP API, але не підходить для кожного завдання. Тіло відповіді може бути XML, двійковим файлом або взагалі бути відсутнім. Заголовок Content-Type повідомляє тип переданих даних; клієнт не повинен вгадувати його за розширенням URL. Параметри запиту, часовий пояс, одиниці вимірювання й кодування слід описувати явно.

Зміна API потребує уваги до зворотної сумісності. Додавання необов’язкового поля часто безпечніше за перейменування наявного; вилучення або зміна типу поля може зламати старих клієнтів. Версію можна зазначати в шляху, заголовку чи іншим способом — універсального варіанта немає. Під час інтеграції фіксуйте, на яку версію контракту спирається клієнт, і перевіряйте оголошений строк підтримки.

REST, SOAP і GraphQL

REST описує архітектурний стиль, а не один обов’язковий формат URL. HTTP API може дотримуватися деяких принципів REST, але сам факт передавання JSON через HTTPS цього не доводить. SOAP задає формат повідомлень і правила їх обробки; його можна зустріти в системах зі строгими контрактами та наявними корпоративними інтеграціями.

GraphQL надає клієнту мову запитів до типізованої схеми: клієнт указує потрібні поля, а сервер виконує запит за правилами схеми. Це може зменшити обсяг зайвих даних, але додає складності в керуванні запитами, авторизації та продуктивності. Порівнювати підходи корисніше за вимогами проєкту, а не за оцінкою, що один із них «сучасний», а інший «застарілий». Історичне визначення вебсервісу наведено в архітектурі W3C.

Автентифікація та дозволи

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

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

Обмеження навантаження, кеш і повтори

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

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

Практична перевірка інтеграції

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

Для діагностики зберігайте час, тип операції й безпечний ідентифікатор запиту, але не повний токен і не особисті дані. Відділяйте помилку DNS від помилки TLS, HTTP-відповіді та помилки обробки даних. Такий розбір допомагає зрозуміти, де виправляти проблему. Приклад чинного інтерфейсу та його можливостей наведено в документації 2IP API.

Що не є вебсервісом

Звичайна сторінка може звертатися до API, але сама по собі не обов’язково надає програмний інтерфейс сторонньому клієнту. FTP передає файли, SSH надає захищений віддалений доступ, а Telnet — це мережевий термінальний протокол без вбудованого шифрування. Їх можна використовувати поруч із вебсервісом під час розгортання чи експлуатації, але називати кожен із них видом вебсервісу неточно. Наприклад, розробник завантажує файли за захищеним протоколом, а вже запущений застосунок надає HTTP API. Різні рівні цієї роботи краще описувати окремо: передавання файлів, адміністрування сервера та інтерфейс обміну даними.

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

Один приклад відповіді не визначає весь сервіс

Перевіряйте також затримку, доступність, помилки й вміст даних за повторюваних умов. За різних прав доступу той самий метод може повертати різні допустимі відповіді.