boxes-api/api_specification.md

# Boxes API - Frontend Specification

This document outlines the API endpoints for a simple inventory management system called "Boxes".

**Authentication:**

* All endpoints (except `/login`) require a valid JWT token in the `Authorization` header, formatted as `Bearer <token>`.
* To obtain a token, send a POST request to `/login` with the following JSON payload:

    ```json
    {
      "username": "your_username",
      "password": "your_password"
    }
    ```

* Successful login will return a JSON response with the token:

    ```json
    {
      "token": "your_jwt_token"
    }
    ```

**Endpoints:**

**1. Boxes:**

* **GET /boxes:**
  * Returns a list of all boxes.
  * Response: Array of Box objects

    ```json
    [
      {
        "id": 1,
        "name": "Kitchen"
      },
      {
        "id": 2,
        "name": "Bedroom"
      }
    ]
    ```

* **POST /boxes:**
  * Creates a new box.
  * Request body: JSON object with the box name

    ```json
    {
      "name": "New Box"
    }
    ```

  * Response: JSON object with the created box's ID and name

    ```json
    {
      "id": 3,
      "name": "New Box"
    }
    ```

* **DELETE /boxes/{id}:**
  * Deletes the box with the specified ID.
  * Response: 204 No Content

**2. Items:**

* **GET /items:**
  * Returns a list of all items.
  * Response: Array of Item objects

    ```json
    [
      {
        "id": 1,
        "name": "Fork",
        "description": "Silverware",
        "box_id": 1,
        "image_path": "path/to/image.jpg" 
      },
      {
        "id": 2,
        "name": "Pillow",
        "description": "Fluffy",
        "box_id": 2,
        "image_path": "path/to/another_image.png" 
      }
    ]
    ```

* **POST /items:**
  * Creates a new item.
  * Request body: JSON object with item details

    ```json
    {
      "name": "Spoon",
      "description": "For soup",
      "box_id": 1,
      "image_path": "path/to/spoon_image.jpg" 
    }
    ```

  * Response: JSON object with the created item's ID and name

    ```json
    {
      "id": 3,
      "name": "Spoon"
    }
    ```

* **GET /items/{id}:**
  * Retrieves the item with the specified ID.
    * Response: Item object
* **GET /boxes/{id}/items:**
  * Retrieves all items within the box with the specified ID.
    * Response: Array of Item objects
* **PUT /items/{id}:**
  * Updates the item with the specified ID.
  * Request body: JSON object with updated item details
  * Response: Updated Item object
* **DELETE /items/{id}:**
  * Deletes the item with the specified ID.
  * Response: 204 No Content