Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Node.js
Code

Створюємо наш перший API за допомогою Node.js та Express: Розбираємося з REST API

by
Difficulty:BeginnerLength:MediumLanguages:
This post is part of a series called Code Your First API With Node.js and Express.
Code Your First API With Node.js and Express: Set Up the Server

Ukrainian (українська мова) translation by AlexBioJS (you can also view the original English article)

Розбираємося з REST та RESTful API

Якщо ви вже мали справу з сучасною веб-розробкою, то зустрічали терміни на зразок REST и API. Якщо ви чули ці терміни або працювали з API, але ще не до кінця зрозуміли принцип їх роботи або як створити свій власний API, то ця серія посібників для вас.

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

Попередні підготування

Для того щоб отримати від цього посібника максимум користі, ви вже повинні мати базові навички роботи з командним рядком, володіти базовими знаннями з JavaScript та мати на своєму комп'ютері встановлену глобально Node.js.

Що собою становлять REST та RESTful API?

За допомогою Representational State Transfer (* передача репрезентативного стану), або REST, описується архітектурний стиль для веб-сервісів. REST складається з набору стандартів та обмежуючих вимог з обміну даними між різними системами, і для систем, що працюють згідно з принципами REST, використовується термін RESTful. REST – абстрактна концепція, це не мова, не фреймворк або тип програмного забезпечення.

Для кращого розуміння REST вам могла би допомогти аналогія, коли порівнюється колекція вінілових пластинок з сервісом для потокової передачі аудіо-даних (* спосіб програвання аудіо- та відеоматеріалів із інтернету без попереднього завантаження їх до комп'ютера). У випадку з вініловими пластинками для їх поширення потрібно, щоб для кожного запису було створено повну копію. У випадку ж сервісом для потокової передачі аудіо-даних та сама музика може поширюватися необмежений термін, якщо відомі будь-які дані, наприклад назва пісні. У цьому випадку сервіс для потокової передачі аудіо-даних є RESTful сервісом, а колекція вінілових пластинок – ні.

API (Application Programming Interface) – інтерфейс, що дозволяє програмам спілкуватися друг з другом. RESTful API – просто API, що працює згідно з принципами та поняттями REST. У випадку з API, що працює у мережі, сервер отримує запит за допомогою кінцевої точки, де вказано URL-адресу, та відправляє назад відповідь, якою часто є дані у форматі на зразок JSON.

Принципи REST

До архітектури REST висуваються шість головних вимог, які наведено нижче:

  1. Уніфікований інтерфейс: інтерфейс компонентів повинен бути однаковим. Це досягається завдяки використанню стандарту URI для ідентифікації ресурсів – іншими словами, шляхів, які могли би бути набрані в адресному рядку браузера.
  2. Клієнт-Сервер: сервер та клієнт виконують різні завдання: сервер зберігає дані та виконує з ними маніпуляції, а клієнт відправляє запити та відображує відповіді.
  3. Взаємодія без запам'ятовування стану: вся інформація про кожний запит міститься у ньому самому та не залежить від стану сесії.
  4. Можливість використання кеш-пам'яті: клієнт та сервер можуть гешувати ресурси.
  5. Багаторівнева система: клієнт може підключатися до кінцевого сервера або проміжного шару на зразок компенсатора (* інструмент для ефективного розподілення трафіку, що надходить до групи серверів).
  6. Отримання коду за запитом (Не обов'язково): клієнт може завантажити код, завдяки чому знижується його видимість у мережі.

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

Ви знаєте, що для всіх веб-сайтів використовується URL-адреса, що починається з http (або https у випадку використання безпечної версії протоколу). HyperText Transfer Protocol, або HTTP, – метод комунікації клієнтів з серверами в Інтернеті.

Нам найочевидніше його існування, коли ми набираємо в адресних рядках наших браузерів URL-адреси, проте HTTP може використовуватися не тільки для запитування веб-сайтів з серверів. Коли ви переходите за URL-адресою, то, власне, виконуєте запит за методом GET для отримання певного ресурсу, і веб-сайт, який ви бачите, є тілом відповіді. Ми скоро розглянемо запити, які виконуються за методом GET та іншими.

HTTP працює, відкриваючи з'єднання TCP (Transmission Control Protocol – протокол керування передаванням) до порту сервера (80 для http, 443 для https) для виконання запиту, а сервер, що прослуховує запити, відправляє відповіді, у яких містяться код відповіді та тіло.

Відповідь повинна складатися з URL, методу, інформації заголовка та тіла.

Методи запиту

Існує чотири головних методи HTTP, відомих також як дієслова HTTP, які часто використовуються для взаємодії з API у мережі. Завдяки цим методам визначається дія, яку буде виконано над будь-яким даним ресурсом.

Методи запиту HTTP приблизно відповідають парадигмі CRUD, що розшифровується як Create, Update, Read, Delete (* створити, прочитати, оновити, видалити). Хоча CRUD відноситься до функцій, що використовуються при виконанні операцій над базою даних, ми можемо застосувати ті основи конструювання до дієслів HTTP у RESTful API.

Дія Метод запиту Визначення
Прочитати GET За допомогою нього виконується отримання ресурсу
Створити POST За допомогою нього виконується створення нового ресурсу
Оновити PUT За допомогою нього виконується оновлення існуючого ресурсу
Видалити DELETE За допомогою нього виконується видалення ресурсу

GET – безпечна операція, що використовується тільки для зчитування даних та при виконанні якої стан сервера не зміниться. Кожного разу, коли ви набираєте у вашому браузері URL-адресу, наприклад https://www.google.com, ви відправляєте запит за методом GET до серверів Google.

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

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

За допомогою запиту за методом DELETE, як повинно бути зрозуміло з його назви, буде просто видалено існуючий ресурс.

Коди відповіді

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

Найвідомішим кодом відповіді для вас повинен бути 404, що позначає Not Found (* повідомляє, що запитуваний ресурс не існує на сервері). 404 входить до складу класу 4xx кодів стану, за допомогою яких вказується, що при обробленні запиту відбулася помилка. Існує п'ять класів кодів стану, у кожному з яких є ряд кодів:

  • 1xx: Information (* Інформація про процес передачі)
  • 2xx: Success (* Інформація про вдалий прийом та оброблення запиту клієнта)
  • 3xx: Redirection (* Перенапрямлення)
  • 4xx: Client Error (* Інформація про помилки з боку клієнта)
  • 5xx: Server Error (* Інформація про помилки з боку сервера)

Іншими поширеними кодами відповіді, з якими ви, скоріш за все, знайомі, є 301 Moved Permanently, що використовується для перенапрямлення браузера за іншою URL-адресою, та 500 Internal Server Error, що вказує на те, що при обробленні запиту відбулася непередбачена помилка на стороні сервера, через що поточний запит не може бути виконаний.

Що стосується API RESTful та їх відповідних дієслів HTTP, то коди всіх відповідей повинні знаходитися у діапазоні 2xx.

Запит Відповідь
GET 200 (OK)
POST 201 (Created) (* Створено)
PUT 200 (OK)
DELETE 200 (OK), 202 (Accepted) (* Прийнято) або 204 (No Content) (* Нема вмісту: тіло повідомлення не передається)

200 OK – код відповіді, що вказує на те, що запит було виконано вдало. Він використовується у якості коду відповіді при відправленні запиту за методом GET або PUT. При виконанні запитів за методом POST буде повернено відповідь з кодом стану 201 Created для вказання того, що новий ресурс було створено, і при виконанні запитів за методом DELETE можливі декілька варіантів кодів відповіді, завдяки яким підтверджується, що або запит було вдало прийнято (202), або відправляти нічого, оскільки ресурс більше не існує (204).

Ми можемо протестувати код стану відповіді на запит ресурсу за допомогою cURL – інструмента командного рядка, що використовується для передачі даних за допомогою URL-адрес. За допомогою команди curl, за якою йде прапорець -i або --include буде відправлено запит за методом GET за вказаною URL-адресою та відображено заголовки та тіло. Ми можемо протестувати це, якщо відкриємо консоль та відправимо запити до Google.

Сервера Google надішлють відповідь з наступною інформацією:

Як видно, у відповідь на запит curl було відправлено багато заголовків та все тіло HTML-відповіді. Оскільки запит було виконано вдало, то першою частиною відповіді є код стану 200 разом з версією HTTP (нею може бути або HTTP/1.1, або HTTP/2).

Оскільки у відповідь на цей конкретний запит у відповіді приходить веб-сайт, то у якості значення заголовка content-type (тип MIME (* Multipurpose Internet Mail Extensions – багатоцільові розширення пошти (поштової служби) в Інтернеті; стандарт на кодування в одному повідомленні текстової і нетекстової інформації  (наприклад, графіки) для передавання електронною поштою в Інтернеті)) вказується text/html. У RESTful API ви, скоріш за все, побачите замість цього application/json, що вказує на те, що форматом відповіді є JSON.

Цікаво те, що ми можемо побачити той чи інший тип відповіді, трохи змінивши адресу, яку набираємо. Виконайте команду curl для відправлення запиту до Google без www.

Google перенапрямить клієнт за адресою www.google.com, і у відповіді буде надіслано код стану 301 для вказання на те, що повинно бути виконано перенапрямлення.

Кінцеві точки RESTful API

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

URL API буде складатися з кореня, шляху та необов'язкового рядка запиту.

  • Корінь, наприклад https://api.example.com або  https://api.example.com/v2, – корінь URL, що може складатися з протоколу, домену та версії протоколу.
  • Шлях, наприклад /users/ або /users/5, – унікальне місцезнаходження певного ресурсу.
  • Параметри запиту (вказувати необов'язково), наприклад ?location=chicago&age=29, – необов'язкові пари ключ=значення, що використовуються для сортування, фільтрації та розбиття контенту на сторінки.
    Ми можемо зібрати ці компоненти докупи для отримання дещо подібного тому, що показано у прикладі нижче, завдяки чому було би повернено список усіх користувачів та використано параметр запиту limit для того, щоб у результаті фільтрації у відповідь було включено тільки 10 результатів.

https://api.example.com/users?limit=10

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

  • Назви шляхів повинно бути вказано у множині: наприклад для того щоб отримати дані про користувача з id 5, ми би скористалися /users/5, а не /user/5.
  • В URL-адресі не повинно міститися розширення файлу: незважаючи на те що при звертанні до кінцевої точки API, скоріш за все, буде повернено файл у форматі JSON, URL не повинен закінчуватися на .json.
  • В URL повинні використовуватися іменники, а не дієслова: слова на зразок add та delete не повинні міститися у URL, що використовується у RESTful API. Для додання нового користувача ви могли би просто відправити POST-запит за адресою, у якій використовується /users, а не щось на зразок /users/add. API повинен розроблятися так, щоб був спроможним обробляти різні типи запитів за тією самою адресою.
  • Шляхи чутливі до регістру клавіатури (великим або рядковим літерам) і повинні бути написані у нижньому регістрі з використанням дефісів, а не символів підкреслення.

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

Завершення

У цьому посібнику ми розглянули, що собою становлять REST та RESTful API, як працюють методи запиту HTTP та коди відповіді, структуру URL API та головні угоди RESTful API. У наступному посібнику ми розглянемо, як застосовувати всю цю теорію на практиці на прикладі створення сервера за допомогою Express та Node.js і створення нашого власного API.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.