REST API для початківців: ресурси, методи, коди стану та відсутність стану

«Вивчіть REST API» — це порада, яку чує кожен новий розробник, проте рідко додається чітке пояснення того, що означає цей вираз. Більшість пояснень або занурюють читача у велику кількість термінології (дієслова, кінцеві точки, відсутність стану), або зводять їх до формулювання «те, що поєднує фронтенд та бекенд», що є правдивим, але не надає жодної корисної інформації.

Цей посібник обирає середній шлях. Ви дізнаєтесь про п’ять основних принципів, з яких складається майже кожен REST API, про ментальну модель, яка допомагає їх краще засвоїти, про те, де REST використовується у повсякденній інженерній роботі, а також про практичну послідовність створення та тестування вашого першого API за допомогою Node.js та Express, разом із поширеними помилками, які найчастіше уповільнюють початківців.

Коротке визначення

REST API — це набір конвенцій, які дозволяють двом програмам спілкуватися через Інтернет. Найчастіше це фронтенд, який запитує у бекенду дані або просить його щось зберегти. Ця ідея здається абстрактною, поки ви її не створите, а потім вона швидко починає здаватися зрозумілою. Саме тому REST зазвичай є одним із перших справжніх концептів бекенду, які вивчають люди, незалежно від того, чи будуть вони спеціалізуватися на роботі з сервером, чи стануть розробниками повного стеку, які працюють з обома частинами додатку.

REST — це скорочення від Representational State Transfer, архітектурний стиль, сформалізований для опису того, як сам веб має функціонувати. Щоб ефективно ним користуватися, не потрібна формальна теорія; саме практичні конвенції, наведені нижче, є основою сучасних REST API.

Чому REST так заплутує багатьох початківців

Два фактори роблять цю тему складнішою, ніж вона має бути.

Першою проблемою є зміна словникового запасу. В Інтернеті термін „API“ використовується майже для будь-якого інтерфейсу, який один програмний продукт надає іншому: API браузера, функції бібліотеки, хмарний сервіс. REST — це один конкретний та дуже популярний спосіб проектування веб-API. Оскільки він настільки поширений, люди часто кажуть „API“, маючи на увазі „REST API“, і тому початківці не розуміють, де закінчується одна концепція та починається інша.

Другою проблемою є відсутність візуального представлення у API. Кнопку чи макет можна побачити; REST API — ні. Цілком можливо тижнями працювати над фронтенд-проектами, вважаючи „виклик API“ чимось незрозумілим. Плутанина зазвичай виникає тоді, коли нарешті потрібно створити власний API, і ця концепція мусить стати конкретною миттєво.

П’ять основних принципів кожного REST API

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

Ресурси та їхні URL

Ресурс — це те, чим керує API: користувачі, дописи, замовлення, завдання. Кожен ресурс або група ресурсів має власну адресу. /users зазвичай позначає групу користувачів, тоді як /orders/42 — конкретне замовлення. Хороша реалізація REST використовує імена ресурсів у вигляді іменників, а метод HTTP описує дію, тому ми бачимо /orders/42, а не /getOrder?id=42.

Методи HTTP

Метод повідомляє серверу, що ви хочете зробити з ресурсом:

• GET — читає дані без їх змін.

POST створює щось нове, зазвичай усередині колекції, наприклад /tasks.

PUT замінює існуючий ресурс, тоді як PATCH оновлює його частину.

DELETE видаляє його.

Однією з властивостей, яку варто зрозуміти рано, є ідемпотентність. Від GET, PUT та DELETE очікується, що вони будуть ідемпотентними: подвійна передача одного й того самого запиту залишає сервер у тому ж стані, що й одноразова передача. POST зазвичай не є ідемпотентним, оскільки два ідентичні запити можуть створити два записи. Це розрізнення пояснює багато рішень щодо проектування API, наприклад чому повторні спроби є безпечними для деяких викликів, а для інших — ризикованими.

Запити та відповіді

Клієнт надсилає запит до одного з цих URL. У запиті містяться метод, URL, заголовки (метадані, такі як тип контенту або токен авторизації), а також, для методів на кшталт POST чи PATCH, тіло запиту. Сервер відповідає результатом, який містить код стану, заголовки та зазвичай тіло відповіді. У сучасних API це тіло майже завжди є у форматі JSON.

Коди стану

Кожна відповідь містить трьохзначне число, яке підсумовує результат. Для успішної операції ви побачите 200, якщо ресурс відсутній — 404, а якщо на сервері сталася помилка — 500. Перша цифра вказує на категорію: 2xx означає успіх, 4xx — клієнт надіслав щось, що сервер не може прийняти (неправильний запит, відсутня автентифікація, невідомий ресурс), а 5xx — у самому сервері виникла проблема. Спочатку переглянувши категорію, ви швидко з’ясуєте, яку частину системи потрібно перевірити.

Безстановість

Кожен запит має містити все необхідне для обробки сервером. Сервер не покладається на пам’ять про те, про що ви просили раніше. Якщо, наприклад, певний кінцевий пункт вимагає автентифікації користувача, кожен запит містить відповідні дані автентифікації, часто у вигляді токена в заголовку. Саме відсутність стану робить REST API легкими для масштабування: будь-яка інстанція сервера може обробляти будь-який запит, оскільки жодна з них не залежить від приватної пам’яті проходження розмови.

Як тільки ці п’ять принципів стануть зрозумілими, документація до REST API більше не буде здаватися іноземною мовою. Майже кожна сторінка довідки, яку ви зустрінете, — це просто список ресурсів, методів, які вони підтримують, форматів тіл запитів та відповідей, а також кодів статусу, які можна отримати.

Ментальна модель: замовлення в ресторані

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

• Меню — це документація API: у ньому перелічено, що ви можете замовити.
• Офіціант — це цикл запиту та відповіді, який приносить ваше замовлення та повертає результат.
• Кухня — це сервер, який виконує роботу, яку ви не бачите безпосередньо.

Якщо уявити це через методи, GET — це запит про те, що є у меню чи перевірка того, що вже на вашому столі. POST — це оформлення нового замовлення. DELETE — це повернення страви назад. Вам не потрібно знати, як внутрішньо організована кухня; достатньо правильно зробити замовлення, щоб отримувати передбачувану та послідовну відповідь щоразу. Ця аналогія має свої обмеження (ресторани пам’ятають ваш столик, тоді як безстанова API — ні), але добре ілюструє розподіл обов’язків.

Де використовується REST у реальній інженерній практиці

REST — це не просто цікавинка з підручників. Це частина щоденної роботи майже кожної команди, що працює над продуктом:

• Розробник фронтенду використовує кінцеві точки REST для завантаження профілю, надсилання форми чи оновлення панелі керування.

Розробник бекенду проєктує та підтримує ці кінцеві точки, вирішуючи, які дані повертати та у якій формі.

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

Мобільні додатки, інтеграції з третіми сторонами та партнерські компанії часто взаємодіють із продуктом виключно через його REST API, без будь-якого користувацького інтерфейсу.

Останній момент є основною причиною того, чому REST став стандартним форматом для веб-API. Ретельно спроєктований набір кінцевих точок може одночасно підтримувати ваш браузерний клієнт, додатки для iOS та Android, а також інтеграцію з зовнішніми партнерами. Ретельний дизайн цих кінцевих точок має велике значення, оскільки кожен клієнт залежить від них; у нашій статті про помилки у контракті API, які погіршують надійність фронтенду розглядається, що відбувається, коли цього не робиться.

Чому REST все ще є правильною відправною точкою

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

По-перше, він є всюди. Більшість публічних API, якими ви, ймовірно, будете користуватися — від постачальників платежів до даних про погоду та соціальних платформ — пропонують інтерфейс REST, часто як стандартний. Ознайомившись з ним один раз, ви отримуєте уявну модель, яку зможете використовувати щоразу, коли будете читати незнайому документацію.

По-друге, він ґрунтується на власній архітектурі Інтернету. Методи HTTP та коди стану були створені не для REST; це протоколи, які вже використовують браузери та сервери. Правильне вивчення REST означає розуміння того, як працює Інтернет під будь-якою фреймворком, який ви використовуєте, і ці знання залишаються актуальними незалежно від конкретних бібліотек.

По-третє, це природний наступний крок після основ фронтенду. Як тільки ви впевнено опануєте HTML, CSS та JavaScript, у момент, коли ваш інтерфейс починає завантажувати справжні дані замість жорстко закодованих замінників, проект зазвичай переходить від прототипу до чогось, що можна справді використовувати. Для багатьох розробників, які орієнтуються на фронтенд, саме тоді створення власного API перестає бути необов’язковим, і починається шлях до роботи з повним стеком. Якщо пізніше ви захочете детально порівняти стилі, перегляньте REST проти GraphQL та компроміси, які стоять за кожною архітектурою.

Створення вашого першого REST API за допомогою Node.js та Express

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

1. Створіть мінімальний сервер, який прослуховуватиме вхідні HTTP-запити на певному порту.
2. Додайте маршрут, наприклад /tasks, та під’єднайте його до обробника GET, який повертає список.
3. Додайте обробник POST на тому самому маршруті, який приймає нові завдання; на цьому етапі достатньо зберігати їх у простому масиві в оперативній пам’яті.
4. Додайте обробники PUT (або PATCH) та DELETE, зазвичай на маршруті /tasks/:id, для оновлення та видалення окремих записів.
5. Як тільки структура API стане зручною, замініть масив на справжню базу даних.
6. Перевірте кожен маршрут за допомогою інструменту на кшталт Postman перед під’єднанням будь-якого фронтенду.

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

Під час роботи повертайте відповідні коди стану замість 200 для всього: 201, коли операція POST створює завдання, 404, коли ідентифікатор id відсутній, 400, коли у тілі запиту відсутнє обов’язкове поле. Саме ці дрібні рішення роблять API зручним для використання.

Де початківці зазвичай застрягають

Люди, які мають труднощі з REST, рідко страждають від браку здібностей. Вони зазвичай зупиняються через передбачувані, виправні причини:

• Одночасне вивчення концепцій REST та фреймворку на кшталт Express, через що ніколи не стає зрозуміло, які правила належать до HTTP, а які — до бібліотеки.
• Відсутність прямого тестування маршрутів за допомогою інструменту на кшталт Postman, що ускладнює розрізнення помилок фронтенду та бекенду.
• Ігнорування кодів статусу та механізмів обробки помилок, що призводить до плутанини, коли клієнт не може відрізнити успіх від невдачі.
• Початок роботи з автентифікацією до того, як будуть налагоджені базові маршрути для створення, читання, оновлення та видалення даних.
• Дослідне використання API з туторіалу без створення чогось простого з іншими ресурсами, що приховує факт зрозуміння концепцій.

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

Адаптація під ваш початковий рівень

Основи залишаються однаковими для всіх, але акцент змінюється залежно від вашої ситуації.

• Студенти отримують перевагу, вивчаючи REST рано, оскільки саме цей підхід зазвичай перетворює особистий проект із статичної сторінки на справжнє додатку.
• Ті, хто шукає роботу, потребують як практичних навичок створення та використання API, так і здатності чітко їх пояснювати, адже запитання про REST трапляються під час співбесід на багато посад.

Люди, які змінюють кар’єру, часто вважають ці ідеї більш доступними, ніж очікувалося; модель ресторану ґрунтується на повсякденному досвіді, а не на технічних знаннях.

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

Звички, які допомагають краще засвоїти концепції

Кілька звичок постійно відрізняють тих, хто справді розуміє REST, від тих, хто лише знає ці терміни.

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

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

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

Поширені запитання початківців

Що таке REST API, одним реченням?

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

Чи потрібно розробникам фронтенду вивчати REST?

Так. Робота з фронтендом передбачає постійне використання REST API, тому майже скрізь очікується їхнє базове розуміння. Це також один із найпростіших варіантів для початку, якщо згодом хочеться перейти до розробки повного стеку.

Чи важко вивчати REST?

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

Чи потрібен диплом з інформатики для створення API бекенду?

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

Чи можна навчитися цьому, працюючи на повну ставку?

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

Підсумок

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

• П’ять ідей складають основу: ресурси з URL, методи HTTP, запити та відповіді, коди стану та безстановість.
• Спочатку вивчіть концепції, а потім використовуйте Express для їх практичного застосування.
• Перевіряйте кожен маршрут окремо, перш ніж від нього почнуть залежати фронтенд-елементи.
• Розглядайте коди стану та обробку помилок як частину проектування, а не як щось додаткове.

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