67 lines
3.3 KiB
Markdown
67 lines
3.3 KiB
Markdown
# REST API: Express, Sequelize i MySQL
|
|
|
|
Serwis REST dla użytkowników, klientów i samochodów. Aplikacja Node.js korzysta z istniejących tabel `users`, `customers` i `cars`; aplikacja nie tworzy ani nie synchronizuje ich automatycznie przy uruchomieniu.
|
|
|
|
## Wymagania i uruchomienie
|
|
|
|
- Node.js 20 lub nowszy
|
|
- MySQL z tabelami używanymi przez dotychczasową aplikację
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env
|
|
```
|
|
|
|
Ustaw w `.env` połączenie do tej samej bazy MySQL co dotychczasowa aplikacja. Następnie wykonaj migrację dodającą unikalne pole `login` do tabeli `users` (dotychczasowym użytkownikom ustawi `login = email`):
|
|
|
|
```bash
|
|
npm run db:migrate
|
|
npm start
|
|
```
|
|
|
|
API działa domyślnie na `http://localhost:8765`, dokumentacja Swagger UI na `http://localhost:8765/docs`, a specyfikacja OpenAPI na `http://localhost:8765/openapi.yaml`. Port można zmienić przez `PORT`.
|
|
|
|
Migrację można cofnąć przez `npx sequelize-cli db:migrate:undo`. Start serwera nigdy nie uruchamia migracji ani `sequelize.sync()`.
|
|
|
|
## Uwierzytelnianie i uprawnienia
|
|
|
|
API używa HTTP Basic Auth: podaj `login` i hasło w nagłówku `Authorization: Basic ...` albo skorzystaj z przycisku **Authorize** w Swagger UI. Loginem jest pole `users.login`; użytkownicy istniejący przed migracją zachowają dotychczasowe dane logowania, bo ich login zostanie ustawiony na adres e-mail.
|
|
|
|
HTTP Basic przesyła hasło w każdym żądaniu; w środowisku produkcyjnym wystawiaj API wyłącznie przez HTTPS.
|
|
|
|
Konta dodawane przez dotychczasowy seeder, o ile istnieją w bazie:
|
|
|
|
| Rola | Login po migracji | Hasło |
|
|
|---|---|---|
|
|
| admin | `admin@example.com` | `Admin123!` |
|
|
| user | `user@example.com` | `User1234!` |
|
|
|
|
Hasła nadal są przechowywane jako bcrypt. Nieaktywne konta nie mogą się uwierzytelniać. Dostęp do `/api/users` wymaga roli `admin`; klienci i samochody są dostępne dla każdego uwierzytelnionego użytkownika.
|
|
|
|
```bash
|
|
curl -u 'admin@example.com:Admin123!' http://localhost:8765/api/auth/me
|
|
curl -u 'user@example.com:User1234!' 'http://localhost:8765/api/customers?q=nowak&with_cars=1'
|
|
```
|
|
|
|
## Endpointy
|
|
|
|
| Metody | Ścieżka | Opis |
|
|
|---|---|---|
|
|
| POST | `/api/auth/login` | Potwierdzenie logowania Basic Auth i aktualizacja `last_login` |
|
|
| GET / PUT / PATCH | `/api/auth/me` | Odczyt i edycja własnego profilu |
|
|
| GET / POST | `/api/users` | Lista i dodawanie użytkowników (admin) |
|
|
| GET / PUT / PATCH / DELETE | `/api/users/{id}` | Odczyt, edycja i usuwanie użytkownika (admin) |
|
|
| GET / POST | `/api/customers` | Lista klientów i dodawanie |
|
|
| GET / PUT / PATCH / DELETE | `/api/customers/{id}` | Szczegóły klienta z samochodami, edycja i usuwanie |
|
|
| GET / POST | `/api/customers/{customer_id}/cars` | Samochody klienta i dodawanie samochodu |
|
|
| GET / POST | `/api/cars` | Lista samochodów i dodawanie |
|
|
| GET / PUT / PATCH / DELETE | `/api/cars/{id}` | Szczegóły samochodu z właścicielem, edycja i usuwanie |
|
|
|
|
Listy obsługują `page`, `limit` (domyślnie 20, maksymalnie 100), `sort` i `direction` (`asc`/`desc`). Endpointy obsługują wyszukiwanie i filtry opisane w Swagger UI; liczba wyników jest zwracana w `X-Total-Count`.
|
|
|
|
## Format odpowiedzi
|
|
|
|
- Sukces: `{"success": true, "data": ...}`; odpowiedź z listą zawiera także `meta`.
|
|
- Błąd walidacji: `{"success": false, "error": {"code": 422, "message": "Validation failed.", "fields": {...}}}`.
|
|
- Usunięcie: `204 No Content`.
|