Announcements API

RESTful API для дошки оголошень на базі Node.js, Express 5, Prisma 7 та SQLite.

Технічний стек

Технологія	Версія	Призначення
Node.js	≥ 18.x	Середовище виконання
Express	^5.2.1	Веб-фреймворк
Prisma	^7.2.0	ORM для роботи з базою даних
better-sqlite3	—	SQLite драйвер (через адаптер)
Celebrate / Joi	^15.0.3	Валідація вхідних даних
Swagger UI	^5.0.1	Інтерактивна документація API
dotenv	^17.2.3	Завантаження змінних оточення

Структура проєкту

api-hw-3/
├── prisma/
│   ├── schema.prisma          # Схема бази даних
│   ├── client.js              # Ініціалізація Prisma Client з адаптером
│   └── migrations/            # Файли міграцій (створюються автоматично)
├── src/
│   ├── controllers/
│   │   └── announcements.controller.js  # Логіка обробки запитів
│   ├── routes/
│   │   └── announcements.routes.js      # Визначення маршрутів + Swagger JSDoc
│   └── validators/
│       └── announcements.validators.js  # Схеми валідації через celebrate
├── generated/                 # Prisma Client (генерується, не комітити)
├── app.js                     # Точка входу, налаштування Express
├── prisma.config.ts           # Конфігурація Prisma CLI
├── requests.http              # Тестові HTTP запити для VS Code REST Client
├── .env                       # Змінні оточення (не комітити)
├── .env.example               # Шаблон змінних оточення
└── package.json

Встановлення та запуск

# 1. Встановити залежності
npm install

# 2. Створити файл змінних оточення
cp .env.example .env

# 3. Створити базу даних і застосувати міграції
npm run prisma:migrate

# 4. Згенерувати Prisma Client
npm run prisma:generate

# 5. Запустити сервер
npm start

Сервер запуститься на http://localhost:3000.

Доступні скрипти

Команда	Дія
npm start	Запуск сервера
npm run dev	Запуск з автоперезавантаженням при змінах
npm run prisma:migrate	Створення та застосування міграцій
npm run prisma:generate	Генерація Prisma Client з поточної схеми

Змінні оточення

DATABASE_URL="file:./prisma/dev.db"

API ендпоінти

Метод	URL	Опис	Статус успіху
GET	/announcements	Список з пошуком і пагінацією	200
GET	/announcements/:id	Одне оголошення за ID	200
POST	/announcements	Створити нове оголошення	201
PATCH	/announcements/:id	Частково оновити оголошення	200
DELETE	/announcements/:id	Видалити оголошення	204

GET /announcements

Query-параметри:

Параметр	Тип	За замовчуванням	Опис
search	string	—	Пошук підрядку в назві
sort	string	newest	newest або oldest
page	number	1	Номер сторінки (10 записів)

Приклад відповіді:

{
  "data": [
    {
      "id": 1,
      "title": "Продам ноутбук ASUS",
      "description": "Відмінний стан, 16GB RAM, SSD 512GB",
      "price": 18000,
      "category": "sale",
      "contactInfo": "0991234567",
      "createdAt": "2025-01-10T12:00:00.000Z",
      "updatedAt": "2025-01-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "totalPages": 1,
    "perPage": 10
  }
}

POST /announcements — тіло запиту

{
  "title": "Продам ноутбук ASUS",
  "description": "Відмінний стан, 16GB RAM, SSD 512GB",
  "price": 18000,
  "category": "sale",
  "contactInfo": "0991234567"
}

PATCH /announcements/:id — тіло запиту

Можна передати будь-яку підмножину полів. Хоча б одне поле обов'язкове.

{
  "price": 16500
}

Валідація

Перевірка відбувається на сервері через бібліотеку celebrate (обгортка над Joi). При помилці повертається статус 400 з деталями.

Правила для полів оголошення:

Поле	Тип	Обмеження
title	string	обов'язкове, від 5 до 100 символів
description	string	обов'язкове, мінімум 10 символів
price	number	обов'язкове, більше нуля
category	string	одне з: sale, service, job, other
contactInfo	string	обов'язкове, мінімум 5 символів

Обробка помилок

Ситуація	HTTP статус
Помилка валідації (celebrate)	400
Невалідний JSON у тілі запиту	400
Оголошення не знайдено (P2025)	404
Маршрут не існує	404
Серверна помилка	500

Документація API

Після запуску сервера інтерактивна Swagger документація доступна за адресою:

http://localhost:3000/api-docs

Там можна переглянути всі ендпоінти і тестувати їх прямо в браузері без додаткових інструментів.

Тестування через VS Code REST Client

У файлі requests.http є готові запити для всіх ендпоінтів, включно з прикладами помилок валідації. Потрібно встановити розширення REST Client для VS Code.