Створюємо наш перший API за допомогою Node.js та Express: Підключаємо базу даних

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

Створюємо API REST за допомогою Node.js та Express: Підключаємо базу даних

У першому посібнику цієї серії, «Understanding RESTful API», ми розглянули, що собою являє архітектура REST, значення методів запиту HTTP та кодів стану відповідей і структуру кінцевої точки RESTful API. У другому посібнику цієї серії, «How to Set Up an Express API Server», ми розглянули, як створювати сервера і за допомогою вбудованого модуля HTTP Node.js, і за допомогою фреймворка Express, а також як задати маршрути для оброблення запитів, виконуваних за різними URL-адресами.

У цей момент ми використовуємо статичні дані для відображення інформації про користувача у форматі JSON при звертанні до кінцевої точки API за допомогою запиту за методом GET. У цьому посібнику ми налаштуємо базу даних MySQL для зберігання даних, підключимося до неї з нашого додатка Node.js та додамо до API можливість використання методів GET, POST, PUT и DELETE для завершення реалізації повноцінного API.

Встановлення

На цей момент ми ще не використовували базу даних для зберігання та виконання маніпуляцій з якимись даними, так що ми встановимо її зараз. У цьому посібнику ми будемо використовувати MySQL, і якщо у вас вже її встановлено, то ви можете перейти до наступного розділу.

Якщо ж ні, то ви можете завантажити MAMP для macOS та Windows, що надає безкоштовну локальну інфраструктуру веб-сервера та базу даних. Після завантаження відкрийте програму та натисніть Start Servers для запуску MySQL.

Окрім налаштування MySQL нам також потрібне програмне забезпечення з GUI для перегляду даних бази. Якщо ви використовуєте Mac, то завантажте SequelPro, якщо Windows – то SQLyog. Після завантаження та запуску MySQL ви можете скористатися SequelPro або SQLyog для підключення до локального сервера за допомогою імені root та паролю root за 3306 портом.

Тільки-но розібралися з цим, ми можемо перейти до створення бази даних для нашого API.

Створюємо базу даних

У програмі для перегляду вашої бази додайте нову базу даних та назвіть її api. Впевніться, що MySQL запущено, або у вас не вийде підключитися до локального сервера.

Після створення бази api перейдіть до неї та виконайте наступний запит для створення нової таблиці.

CREATE TABLE `users` (
  `id`       int(11)     unsigned NOT NULL AUTO_INCREMENT,
  `name`     varchar(30) DEFAULT '',
  `email`    varchar(50) DEFAULT '',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

За допомогою цього запиту SQL буде створено структуру таблиці з нашими користувачами. У кожного користувача буде id, значення якого збільшується автоматично, ім'я та адреса електронної пошти.

Також ми можемо заповнити базу даних тими самими даними, які у цей момент відображуємо, використовуючи статичний масив даних у форматі JSON, за допомогою запиту INSERT.

INSERT INTO users (name, email) 
     VALUES ('Richard Hendricks', 'richard@piedpiper.com'), 
            ('Bertram Gilfoyle',  'gilfoyle@piedpiper.com');

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

Підключаємося до MySQL

Повертаємося до нашого додатка, де нам потрібно підключитися до MySQL з Node.js для початку роботи з даними. Раніше ми встановили модуль npm mysql і тепер ми їм скористаємося.

Створіть нову папку під назвою data та файл config.js.

Ми почнемо із запитування модуля mysql у data/config.js.

const mysql = require('mysql');

Давайте створимо об'єкт config, у якому будуть знаходитися дані про хост, ім'я користувача, його пароль та назва бази. У ньому повинно бути вказано базу даних api, що ми створили, та повинні використовуватися налаштування за налаштуванням локального сервера.

// Set database connection credentials
const config = {
    host: 'localhost',
    user: 'root',
    password: 'root',
    database: 'api',
};

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

// Create a MySQL pool
const pool = mysql.createPool(config);

Нарешті, ми експортуємо пул MySQL, завдяки чому додаток зможе їм скористатися.

// Export the pool
module.exports = pool;

Ви можете ознайомитися з повним конфігураційним файлом у нашому репозиторії GitHub.

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

Отримання даних з MySQL

У цей момент у нашому файлі routes.js масив з даними про користувачів у форматі JSON створюється вручну та виглядає наступним чином:

const users = [{ ...

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

// Load the MySQL pool connection
const pool = require('../data/config');

Раніше при запитах за методом GET за адресою /users назад поверталися статичні дані, що зберігаються у змінній users. У нашому оновленому коді ці дані будуть запитуватися із бази даних. Ми скористаємося запитом SQL SELECT для вибору всіх даних із таблиці users, що виглядає наступним чином:

SELECT * FROM users

Нижче показано, як буде виглядати наша кінцева точка для оброблення запитів за методом GET, що надходять за адресою /users, у якій використовується метод pool.query().

// Display all users
app.get('/users', (request, response) => {
    pool.query('SELECT * FROM users', (error, result) => {
        if (error) throw error;

        response.send(result);
    });
});

Тут ми виконуємо запит SELECT і потім відправляємо результат у форматі JSON клієнту за допомогою кінцевої точки, у якості URL-адреси якої вказано /users. Якщо ви перезапустите сервер та перейдете на сторінку за адресою /users, то побачите ті самі дані, що й раніше, проте у цей раз вони надходять динамічно.

Використання параметрів URL

На цей момент URL-адреси наших кінцевих точок являють собою статичні шляхи – будь то / або /users, але що якщо нам потрібно отримати дані тільки про певного користувача. Нам потрібно буде використовувати змінливу URL-адресу кінцевої точки.

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

// Display a single user by ID
app.get('/users/:id', (request, response) => {
        ...
    });
});

Ми можемо отримати значення цього параметра за допомогою властивості request.params. Оскільки наша властивість називається id, то ми отримаємо її наступним чином:

const id = request.params.id;

Тепер ми додамо умову WHERE до нашого запиту SELECT для того, щоб отримувати тільки результати з указаним id.

Ми скористаємося ? у якості заповнювача для запобігання атаці у вигляді проникнення коду SQL та передамо id у якості параметра, а не будемо створювати рядок за допомогою конкатенації, що було би небезпечніше.

pool.query('SELECT * FROM users WHERE id = ?', id, (error, result) => {
    if (error) throw error;

    response.send(result);
});

Повний код ресурсу для отримання індивідуального користувача тепер виглядає наступним чином:

// Display a single user by ID
app.get('/users/:id', (request, response) => {
    const id = request.params.id;

    pool.query('SELECT * FROM users WHERE id = ?', id, (error, result) => {
        if (error) throw error;

        response.send(result);
    });
});

Тепер ви можете перезапустити сервер та перейти за https://localhost/users/2 для ознайомлення з інформацією тільки про Gilfoyle. У випадку помилки на зразок Cannot GET /users/2 перезапустіть браузер.

При переході за цією URL-адресою буде повернено єдиний результат.

[{
    id: 2,
    name: "Bertram Gilfoyle",
    email: "gilfoyle@piedpiper.com"
}]

Якщо це так, то мої вітання: ви вдало створили динамічний параметр маршруту!

Відправлення запиту за методом POST

Поки що все, що ми виконувати, опосередковувалося запитами за методом GET. Ці запити безпечні, тобто вони не змінюють стан сервера. Ми просто переглядали дані у форматі JSON.

Тепер ми почнемо перетворювати наш API у динамічний завдяки використанню запиту за методом POST для додання нових даних.

Я згадала раніше, у «Understanding REST», що не варто використовувати дієслова на зразок add або delete в URL для виконання дій. Для того щоб додати нового користувача до бази даних, ми будемо виконувати запит за методом POST за тією самою URL-адресою, яку використовували для їх перегляду, проте просто встановимо для нього окремий шлях.

// Add a new user
app.post('/users', (request, response) => {
    ...
});

Зверніть увагу, що ми тепер використовуємо app.post() замість app.get().

Оскільки ми створюємо, а не зчитуємо, то скористаємося тут запитом INSERT, подібно до того, як ми робили при ініціалізації бази даних. Ми відправимо цілу властивість request.body у запиті SQL.

pool.query('INSERT INTO users SET ?', request.body, (error, result) => {
    if (error) throw error;

Також ми зазначимо у якості статусу відповіді як 201, що позначає Created. Для того щоб отримати id останнього доданого користувача, ми скористаємося властивістю insertId.

response.status(201).send(`User added with ID: ${result.insertId}`);

Код для маршруту, який приймає запити за методом POST, буде виглядати наступним чином:

// Add a new user
app.post('/users', (request, response) => {
    pool.query('INSERT INTO users SET ?', request.body, (error, result) => {
        if (error) throw error;

        response.status(201).send(`User added with ID: ${result.insertId}`);
    });
});

Тепер ми можемо відправити запит за методом POST. У більшості випадків, коли ви відправляєте запит за методом POST, ви це здійснюєте за допомогою веб-форми. Ми розберемося з цим ближче до кінця посібника, проте найшвидший та найлегший спосіб відправлення пробного запиту за методом POST – за допомогою cURL, використовуючи прапорець -d (--data).

Ми виконаємо команду curl -d, розмістивши після неї рядок запиту з усіма парами ключ=значення та запитувану кінцеву точку.

curl -d "name=Dinesh Chugtai&email=dinesh@piedpiper.com" http://localhost:3002/users

Одразу після відправлення цього запиту ви повинні отримати відповідь від сервера.

User added with ID: 3

Якщо ви перейдете за http://localhost/users, то побачите останній доданий до таблиці користувачів запис.

Відправлення запиту за методом PUT

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

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

Давайте створимо запит UPDATE та впевнимося за допомогою умови WHERE, що він застосовується тільки до запитаного id. Ми використовуємо два заповнювачі ?, і передавані нами дані будуть додаватися послідовно.

// Update an existing user
app.put('/users/:id', (request, response) => {
    const id = request.params.id;

    pool.query('UPDATE users SET ? WHERE id = ?', [request.body, id], (error, result) => {
        if (error) throw error;

        response.send('User updated successfully.');
    });
});

Переходимо до тестування. Ми відредагуємо користувача під номером 2 та змінимо адресу електронної пошти з gilfoyle@piedpiper.com на bertram@piedpiper.com. Ми можемо використати cURL знову з прапорцем [-X (--request)], для того щоб явно вказати, що ми відправляємо запит за методом PUT.

curl -X PUT -d "name=Bertram Gilfoyle" -d "email=bertram@piedpiper.com" http://localhost:3002/users/2

Перезапустіть браузер перед відправленням запиту, інакше ви отримаєте помилку Cannot PUT /users/2.

Ви повинні будете побачити наступне:

User updated successfully.

Користувацькі дані зі значенням id, що дорівнює 2, тепер повинно бути оновлено.

Відправлення запитів за методом DELETE

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

// Delete a user
app.delete('/users/:id', (request, response) => {
    const id = request.params.id;

    pool.query('DELETE FROM users WHERE id = ?', id, (error, result) => {
        if (error) throw error;

        response.send('User deleted.');
    });
});

Ми можемо використовувати -x для відправлення запиту на видалення даних. Давайте видалимо останнього користувача, якого створили.

curl -X DELETE http://localhost:3002/users/3

Ви побачите оповіщення про вдале завершення операції.

User deleted.

Перейдіть за http://localhost:3002 і ви побачите, що тепер залишилося тільки двоє користувачів.

Мої вітання! Тепер API завершений. Відвідайте репозиторій GitHub, щоб ознайомитися з повним кодом routes.js.

Відправлення запитів за допомогою модуля `request`

На початку цього посібника ми встановили чотири залежності, і однією з них був модуль request. Замість виконання запитів за допомогою cURL ви могли би створити новий файл з усіма даними та відправити їх за допомогою нього. Я створю файл під назвою post.js, завдяки якому буде створено нового користувача за допомогою відправлення запиту за методом POST.

const request = require('request');

const json = {
    "name": "Dinesh Chugtai",
    "email": "dinesh@piedpiper.com",
};

request.post({
    url: 'http://localhost:3002/users',
    body: json,
    json: true,
}, function (error, response, body) {
    console.log(body);
});

Ми можемо запустити цей файл завдяки виконанню команди node post.js у новому вікні консолі, не зупиняючи сервер, і в результаті отримаємо той самий результат, як і при використанні cURL. Якщо при використанні cURL щось не те, то модуль request стає у пригоді, оскільки ми можемо ознайомитися з помилками, відповіддю та тілом повідомлення.

Відправлення запитів за допомогою веб-форми

Звичайно запити, які відправляються за методом HTTP POST та рештою, при виконанні яких змінюється стан сервера, відправляються за допомогою HTML-форм. У цьому дуже простому прикладі ми можемо створити файл index.html будь-де та поля для заповнення імені та адреси електронної пошти. У якості адреси обробника (* до якого звертаються дані форми при їх відправленні на сервер) форми буде вказано адресу ресурсу, у нашому випадку http//localhost:3002/users, і ми вкажемо у якості методу post.

Створіть index.html та додайте туди наступний код:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>Node.js Express REST API</title>
</head>

<body>
    <form action="http://localhost:3002/users" method="post">
        <label for="name">Name</label>
        <input type="text" name="name">
        <label for="email">Email</label>
        <input type="email" name="email">
        <input type="submit">
    </form>
</body>

</html>

Відкрийте цей статичний HTML-файл у вашому браузері, заповніть форму та відправте її, не відключаючи сервер. Ви повинні будете побачити у якості відповіді User added with ID: 4, а також новий список користувачів.

Завершення

У цьому посібнику ми розібралися з тим, як підключити сервер Express до бази даних MySQL та налаштувати маршрути, які відповідають методам GET, POST, PUT та DELETE, де вказуються певні шляхи та динамічні параметри маршруту. Також ми дізналися, як відправляти запити HTTP до API для сервера за допомогою cURL, модуля request Node.js та HTML-форм.

До цього моменту у вас повинно було би скластися дуже ясне уявлення про те, як працюють RESTful API, і тепер ви можете створити ваш власний повністю працездатний API, що працює на основі платформи Node.js, за допомогою Express та MySQL!