API на швидкості блискавки: обслуговування безпосередньо з бази даних

Втомились від нескінченної шаблонної роботи з API для ваших маленьких проєктів? Попрощайтеся з цією проблемою! Знайомтесь з PostgREST — супергероєм, який перетворює вашу базу даних на потужне RESTful API за кілька хвилин. Більше ніяких нудних кодів, тільки чиста продуктивність!

https://tripleviking.com/blogs/news/what-did-viking-armor-really-look-like

PostgREST — це окремий веб-сервер, який безпосередньо перетворює вашу базу даних PostgreSQL на RESTful API. Структурні обмеження та права доступу в базі даних визначають кінцеві точки API та операції.

КРОК 1: Встановлення PostgRest

a. MacOs

brew install postgrest

b. Windows
Ви можете встановити через chocolatey або scoop.

choco install postgrest  
scoop install postgrest

c. Linux
Ви можете завантажити бінарний файл з тут. Додаю зображення для посилання.

Зображення для бінарних файлів

Оскільки я використовую Ubuntu/x86_64, я завантажив postgrest-v12.2.3-linux-static-x64.tar.xz. Завантажте відповідно до вашої системи OS/Архітектури.

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

sudo mv postgrest /usr/local/bin/postgrest  
sudo chmod +x /usr/local/bin/postgrest

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

postgrest --version

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

КРОК 2: Встановлення PostgreSQL

a. Через Docker

Якщо у вас вже встановлений Docker, то налаштування PostgreSQL значно спрощується. Якщо Docker ще не встановлено, завантажте його тут.

Виконайте наступну команду для установки та запуску бази даних. Сподіваюся, ви знайомі з командами Docker, якщо ні — не хвилюйтеся, просто запустіть її, і повірте, все працюватиме.

sudo docker run --name tutorial -p 5432:5432 \  
 -e POSTGRES_PASSWORD=notused \  
 -d postgres

Ця команда завантажить образ PostgreSQL (якщо він ще не завантажений) і запустить контейнер у Docker-демоні.

• --name дає контейнеру ім'я tutorial.
• -p мапить порт хоста 5432 на порт контейнера 5432 (hostport:containerport). Якщо інший сервіс вже використовує порт 5432, ви можете налаштувати інший порт хоста (наприклад, -p 8080:5432).
• -e встановлює змінну середовища POSTGRES_PASSWORD в контейнері на notused.
• -d запускає контейнер в відокремленому режимі, щоб він продовжував працювати навіть після закриття термінала.

b. Встановлення PostgreSQL без Docker

Ви можете завантажити сервер postgres безпосередньо на ваш комп'ютер. Я вже встановив Postgres на свою машину і використовую його для обробки API запитів. Завантажити його можна тут.

КРОК 3. Створення бази даних для API

Підключіться до SQL консолі (psql) всередині контейнера. Для цього виконайте наступну команду в терміналі:

sudo docker exec -it tutorial psql -U postgres

Тепер ви повинні побачити командний рядок psql:

psql (16.2)  
Type "help" for help.  

postgres=#

Я сподіваюся, ви знайомі з основними SQL командами, такими як створення таблиць, вставка значень тощо.

Тепер давайте створимо схему, яку можна буде експонувати через API.
Виконайте наступну команду.

CREATE SCHEMA api;

Тепер давайте створимо таблицю todos, яка буде відповідальна за обробку запиту на кінцеву точку \todos.

CREATE TABLE api.todos (  
 id SERIAL PRIMARY KEY,  
 task TEXT NOT NULL,  
 done BOOLEAN NOT NULL DEFAULT FALSE,  
 due timestamp  
);

Додайте деякі дані до таблиці.

INSERT INTO api.todos (task)  
VALUES  
 ('Learn Postgrest'),  
 ('Write blog on Postgrest');

Не підключайте свою базу даних через обліковий запис адміністратора (який має права на рівні бога, і жодні обмеження не можуть йому завадити), наприклад, через postgres, оскільки будь-хто з доступом до API може пошкодити вашу базу даних. Краще створити роль з обмеженими правами, згідно з вашими потребами, для підключення, щоб ніхто не зміг пошкодити вашу базу даних.

Давайте створимо нову роль.

CREATE ROLE web_anon NOLOGIN;  

GRANT USAGE ON SCHEMA api TO web_anon;  
GRANT SELECT ON api.todos TO web_anon;

У наведених вище командах ми створили роль web_anon з правами NOLOGIN, що означає, що ця роль не може використовуватися для прямого підключення до бази даних. Уявіть цю роль як тренера — вона має навички (права в цьому випадку), але не грає (не може підключатися сама). Замість цього навички цієї ролі (права) можуть бути використані безпосередньо через API або передані іншим ролям/користувачам, які успадковують або отримують ці права.

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

CREATE ROLE authenticator NOINHERIT LOGIN PASSWORD 'mysecretpassword';  
GRANT web_anon TO authenticator;

У наведених вище командах ми створили роль authenticator з властивістю NOINHERIT, що означає, що вона не успадковує права від ролей, яким вона надається. Ця роль має права LOGIN, що дозволяє підключатися до бази даних, використовуючи пароль mysecretpassword. Команда GRANT web_anon TO authenticator; дозволяє ролі authenticator отримати доступ до прав, наданих ролі web_anon, але тільки після явного налаштування через команду SET ROLE web_anon після входу.

Тепер вийдемо з psql; настав час запустити API!

\q

КРОК 4: Запуск PostgREST

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

db-uri = "postgres://authenticator:mysecretpassword@localhost:5432/postgres"  
db-schemas = "api"  
db-anon-role = "web_anon"

Конфігураційний файл має інші опції, але для старту сервера цього достатньо.

УВАГА: Якщо ви використовували інший порт, окрім 5432, замініть його в db-uri.

Тепер виконайте наступну команду, щоб запустити сервер.

# якщо бінарний файл знаходиться в глобальному шляху виконуваних файлів  
postgrest tutorial.conf  

# якщо бінарний файл не знаходиться в глобальному шляху виконуваних файлів, перейдіть в каталог, де  
# знаходиться бінарний файл  
./postgrest tutorial.conf

Ви повинні побачити щось подібне до цього:

Журнал сервера Postgrest

Тепер ви можете використовувати команду curl або відкрити браузер і ввести наступну URL-адресу http://localhost:3000/todos. Ви побачите JSON-відповідь з вашими даними.

Ви також можете вибрати конкретний стовпець і відфільтрувати відповідь на основі вашого умови.
Напишіть цю URL-адресу http://localhost:3000/todos?select=task&id=eq.1 у рядку адреси вашого браузера, щоб побачити наступний результат:

Вибір конкретного стовпця та фільтрація відповіді.

Ви не зможете надіслати дані, оскільки ми дозволили тільки select — права для читання. Якщо ви спробуєте, отримаєте наступний результат:

Неуспішний запит на відправку даних

Зверніться до офіційної документації, щоб дізнатися більше про запити до API, і обов'язково перегляньте PostgREST, щоб дізнатися більше. У наступному блозі ми розглянемо автентифікацію та запити на відправку.

Перекладено з: API at Lightning Speed: Serve Directly from the Database