paprika-api/API_DOCS.md

# Paprika API Documentation

The Paprika API provides endpoints for user authentication, managing restaurant menus, and menu items.

## Base URL
The base URL for the API is `http://localhost:3333` (default for AdonisJS development).

## Authentication

Authentication is handled via Bearer tokens. Include `Authorization: Bearer <token>` in the headers for protected routes.

### Register
Registers a new user.

- **URL:** `/api/register`
- **Method:** `POST`
- **Body:**
  - `email` (string, required): The user's email address.
  - `password` (string, required): The user's password.
  - `fullName` (string, optional): The user's full name.
- **Response:** User access token object.

### Login
Authenticates a user and returns an access token.

- **URL:** `/api/login`
- **Method:** `POST`
- **Body:**
  - `email` (string, required): The user's email address.
  - `password` (string, required): The user's password.
- **Response:** User access token object.

### Logout
Logs out the current user by deleting the access token.

- **URL:** `/api/logout`
- **Method:** `DELETE`
- **Authentication:** Required
- **Response:** `{"message": "User logged out"}`

### Get Me
Retrieves information about the currently authenticated user.

- **URL:** `/api/me`
- **Method:** `GET`
- **Authentication:** Required
- **Response:** `{"user": { ...user data... }}` or `{"message": "Unauthorized"}`

---

## Restaurant Menus

### Get All Menus
Retrieves all restaurant menus, preloading items and their categories.

- **URL:** `/api/menus`
- **Method:** `GET`
- **Response:** Array of menu objects.

### Get One Menu
Retrieves a single restaurant menu by ID, preloading items and their categories.

- **URL:** `/api/menus`
- **Method:** `POST`
- **Body:**
  - `id` (number, required): The ID of the menu to retrieve.
- **Response:** Menu object.

### Create Menu
Creates a new restaurant menu.

- **URL:** `/api/menus/create`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `name` (string, required): The name of the menu (e.g., "2025.09.08. Hétfő").
  - `nameHu` (string, optional): Hungarian translation of the menu name.
  - `nameEn` (string, optional): English translation of the menu name.
- **Response:** Created menu object.

### Update Menu
Updates an existing restaurant menu.

- **URL:** `/api/menus`
- **Method:** `PUT`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the menu to update.
  - `name` (string, optional): The new name of the menu.
  - `nameHu` (string, optional): The new Hungarian name of the menu.
  - `nameEn` (string, optional): The new English name of the menu.
- **Response:** Updated menu object.

### Delete Menu
Deletes a restaurant menu and detaches all connected menu items.

- **URL:** `/api/menus`
- **Method:** `DELETE`
- **Authentication:** Required (Admin)
- **Rate Limited:** Yes
- **Body:**
  - `id` (number, required): The ID of the menu to delete.
- **Response:** `{"message": "Menu deleted"}` or error.

---

## Restaurant Menu Items

### Get All Menu Items
Retrieves all restaurant menu items, preloading category and menus.

- **URL:** `/api/menu-items`
- **Method:** `GET`
- **Response:** Array of menu item objects.

### Get One Menu Item
Retrieves a single restaurant menu item by ID, preloading category and menus.

- **URL:** `/api/menu-items`
- **Method:** `POST`
- **Body:**
  - `id` (number, required): The ID of the menu item to retrieve.
- **Response:** Menu item object.

### Create Menu Item
Creates a new restaurant menu item. Note: This item must be manually attached to a menu using the `/api/menu-items/attach` endpoint.

- **URL:** `/api/menu-items/create`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `name` (string, required): The name of the menu item.
  - `nameHu` (string, required): Hungarian translation of the item name.
  - `nameEn` (string, required): English translation of the item name.
  - `priceSmall` (number, required): The price for a small serving.
  - `priceLarge` (number, required): The price for a large serving.
  - `description` (string, optional): General description of the menu item.
  - `descriptionHu` (string, optional): Hungarian translation of the description.
  - `descriptionEn` (string, optional): English translation of the description.
  - `categoryId` (number, optional): The ID of the category this item belongs to.
- **Response:** Created menu item object.

### Update Menu Item
Updates an existing restaurant menu item.

- **URL:** `/api/menu-items`
- **Method:** `PUT`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the menu item to update.
  - `name` (string, optional): The new name.
  - `nameHu` (string, optional): The new Hungarian name.
  - `nameEn` (string, optional): The new English name.
  - `priceSmall` (number, optional): The new price for small.
  - `priceLarge` (number, optional): The new price for large.
  - `description` (string, optional): The new description.
  - `descriptionHu` (string, optional): The new Hungarian description.
  - `descriptionEn` (string, optional): The new English description.
  - `categoryId` (number, optional): The new category ID.
- **Response:** Updated menu item object.

### Attach Menu Item to Menu
Connects an existing menu item to a menu (many-to-many relationship).

- **URL:** `/api/menu-items/attach`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Rate Limited:** No
- **Body:**
  - `item_id` (number, required): The ID of the menu item to attach.
  - `menu_id` (number, required): The ID of the menu to attach the item to.
- **Response:** `{"message": "Menu item connected to menu"}`

### Delete Menu Item
Deletes a restaurant menu item and detaches it from all menus.

- **URL:** `/api/menu-items`
- **Method:** `DELETE`
- **Authentication:** Required (Admin)
- **Rate Limited:** Yes
- **Body:**
  - `id` (number, required): The ID of the menu item to delete.
- **Response:** `{"message": "Menu item deleted"}` or error.

---

## Users (Administrators Only)

### Get All Users
Retrieves all users.

- **URL:** `/api/users`
- **Method:** `GET`
- **Authentication:** Required (Admin)
- **Response:** Array of user objects.

### Get One User
Retrieves a single user by ID.

- **URL:** `/api/users/get-one`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the user to retrieve.
- **Response:** User object.

### Update User
Updates an existing user.

- **URL:** `/api/users`
- **Method:** `PUT`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the user to update.
  - `email` (string, optional): The new email of the user.
  - `fullName` (string, optional): The new full name of the user.
  - `role` (string, optional): The new role of the user (e.g., 'user', 'admin').
- **Response:** Updated user object.

### Delete User
Deletes a user.

- **URL:** `/api/users`
- **Method:** `DELETE`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the user to delete.
- **Response:** `{"message": "User deleted"}` or success.

---

## Categories

### Get All Categories
Retrieves all categories.

- **URL:** `/api/categories`
- **Method:** `GET`
- **Response:** Array of category objects.

### Get One Category
Retrieves a single category by ID.

- **URL:** `/api/categories`
- **Method:** `POST`
- **Body:**
  - `id` (number, required): The ID of the category to retrieve.
- **Response:** Category object.

### Create Category
Creates a new category.

- **URL:** `/api/categories/create`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `name` (string, required): The name of the category.
  - `nameHu` (string, optional): Hungarian translation of the name.
  - `nameEn` (string, optional): English translation of the name.
  - `slug` (string, required): The slug of the category.
- **Response:** Created category object.

### Update Category
Updates an existing category.

- **URL:** `/api/categories`
- **Method:** `PUT`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the category to update.
  - `name` (string, optional): The new name.
  - `nameHu` (string, optional): The new Hungarian name.
  - `nameEn` (string, optional): The new English name.
  - `slug` (string, optional): The new slug.
- **Response:** Updated category object.

### Delete Category
Deletes a category.

- **URL:** `/api/categories`
- **Method:** `DELETE`
- **Authentication:** Required (Admin)
- **Rate Limited:** Yes
- **Body:**
  - `id` (number, required): The ID of the category to delete.
- **Response:** `{"message": "Category deleted"}` or error.

---

## Images

### List Images
Retrieves a list of all uploaded images.

- **URL:** `/api/images`
- **Method:** `GET`
- **Authentication:** Required (Admin)
- **Response:** `[{"filename": "...", "url": "...", "thumbnailUrl": "..."}]`

### Upload Image
Uploads an image for menu items or categories. Supported extensions: jpg, jpeg, png, webp, gif. Max size: 10mb. Automatically generates a 200px wide thumbnail.

- **URL:** `/api/images/upload`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `image` (file, required): The image file to upload.
- **Response:** `{"filename": "...", "url": "...", "thumbnailUrl": "..."}`

### Show Image
Retrieves and displays a previously uploaded image.

- **URL:** `/api/images/:filename`
- **Method:** `GET`
- **Query Parameters:**
  - `type` (string, optional): Use `thumbnail` to retrieve the 200px wide thumbnail.
- **Response:** Image stream with correct MIME type.

---

## Room Reservations

### Get All Rooms
Retrieves a list of all available rooms.

- **URL:** `/api/room-reservations/rooms`
- **Method:** `GET`
- **Response:** Array of room objects.

### Create Room
Creates a new room.

- **URL:** `/api/room-reservations/rooms`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `name` (string, required): The name of the room.
  - `capacity` (number, required): The capacity of the room.
  - `description` (string, optional): A description of the room.
- **Response:** Created room object.

### Update Room
Updates an existing room.

- **URL:** `/api/room-reservations/rooms`
- **Method:** `PUT`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the room to update.
  - `name` (string, optional): The new name.
  - `capacity` (number, optional): The new capacity.
  - `description` (string, optional): The new description.
- **Response:** Updated room object.

### Delete Room
Deletes a room.

- **URL:** `/api/room-reservations/rooms`
- **Method:** `DELETE`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the room to delete.
- **Response:** `{"message": "Room deleted"}`

### Get All Reservations
Retrieves a list of all room reservations, preloading room details.

- **URL:** `/api/room-reservations/reservations`
- **Method:** `GET`
- **Response:** Array of reservation objects.

### Create Reservation
Creates a new room reservation.

- **URL:** `/api/room-reservations/reservations`
- **Method:** `POST`
- **Authentication:** Required (Admin)
- **Body:**
  - `roomId` (number, required): The ID of the room.
  - `customerName` (string, required): The name of the customer.
  - `customerPhone` (string, required): The phone number of the customer.
  - `guestsCount` (number, required): Number of guests.
  - `startsAt` (string, required): Start time (ISO 8601).
  - `endsAt` (string, required): End time (ISO 8601).
  - `notes` (string, optional): Additional notes.
- **Response:** Created reservation object.

### Update Reservation
Updates an existing reservation.

- **URL:** `/api/room-reservations/reservations`
- **Method:** `PUT`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the reservation to update.
  - `roomId` (number, optional): The new room ID.
  - `customerName` (string, optional): The new customer name.
  - `customerPhone` (string, optional): The new customer phone.
  - `guestsCount` (number, optional): The new guests count.
  - `startsAt` (string, optional): The new start time.
  - `endsAt` (string, optional): The new end time.
  - `status` (string, optional): The new status ('confirmed' or 'cancelled').
  - `notes` (string, optional): New notes.
- **Response:** Updated reservation object.

### Delete Reservation
Deletes a reservation.

- **URL:** `/api/room-reservations/reservations`
- **Method:** `DELETE`
- **Authentication:** Required (Admin)
- **Body:**
  - `id` (number, required): The ID of the reservation to delete.
- **Response:** `{"message": "Reservation deleted"}`

---

## Rate Limiting
Some endpoints (like login, registration, and deletion) are protected by rate limiting to prevent abuse. If you receive a `429 Too Many Requests` response, please wait before trying again.