boxes-api/api_reference.md

# API Reference

## Base URL
```
http://<your-server-address>:<port>
```

## Authentication
All endpoints (except `/login`) require a valid JWT token in the `Authorization` header. The token is prefixed with `Bearer `.

---

## Endpoints

### 1. **Login**
- **Endpoint:** `/login`
- **Method:** `POST`
- **Request Body:**
  ```json
  {
    "username": "string",
    "password": "string"
  }
  ```
- **Response:**
  ```json
  {
    "token": "string"
  }
  ```
- **Description:** Authenticates a user and returns a JWT token.

---

### 2. **Get Boxes**
- **Endpoint:** `/boxes`
- **Method:** `GET`
- **Response:**
  ```json
  [
    {
      "id": "integer",
      "name": "string"
    },
    ...
  ]
  ```
- **Description:** Retrieves all boxes.

---

### 3. **Create Box**
- **Endpoint:** `/boxes`
- **Method:** `POST`
- **Request Body:**
  ```json
  {
    "name": "string"
  }
  ```
- **Response:**
  ```json
  {
    "id": "integer",
    "name": "string"
  }
  ```
- **Description:** Creates a new box and returns its ID.

---

### 4. **Delete Box**
- **Endpoint:** `/boxes/{id}`
- **Method:** `DELETE`
- **Description:** Deletes a box by its ID.

---

### 5. **Get Items**
- **Endpoint:** `/items`
- **Method:** `GET`
- **Response:**
  ```json
  [
    {
      "id": "integer",
      "name": "string"
    },
    ...
  ]
  ```
- **Description:** Retrieves all items.

---

### 6. **Create Item**
- **Endpoint:** `/items`
- **Method:** `POST`
- **Request Body:**
  ```json
  {
    "name": "string",
    "description": "string",
    "box_id": "integer"
  }
  ```
- **Response:**
  ```json
  {
    "id": "integer",
    "name": "string"
  }
  ```
- **Description:** Creates a new item and returns its ID.

---

### 7. **Get Item**
- **Endpoint:** `/items/{id}`
- **Method:** `GET`
- **Response:**
  ```json
  {
    "id": "integer",
    "name": "string",
    "description": "string",
    "box_id": "integer"
  }
  ```
- **Description:** Retrieves an item by its ID.

---

### 8. **Update Item**
- **Endpoint:** `/items/{id}`
- **Method:** `PUT`
- **Request Body:**
  ```json
  {
    "name": "string",
    "description": "string",
    "box_id": "integer"
  }
  ```
- **Response:**
  ```json
  {
    "id": "integer",
    "name": "string"
  }
  ```
- **Description:** Updates an item by its ID.

---

### 9. **Delete Item**
- **Endpoint:** `/items/{id}`
- **Method:** `DELETE`
- **Description:** Deletes an item by its ID.

---

### 10. **Get Items in Box**
- **Endpoint:** `/boxes/{id}/items`
- **Method:** `GET`
- **Response:**
  ```json
  [
    {
      "id": "integer",
      "name": "string"
    },
    ...
  ]
  ```
- **Description:** Retrieves all items within a specified box.

---

### 11. **Upload Item Image**
- **Endpoint:** `/items/{id}/upload`
- **Method:** `POST`
- **Form Data:**
  - **File:** `image` (the image file to upload)
- **Response:**
  ```json
  {
    "imagePath": "string"
  }
  ```
- **Description:** Uploads an image for a specified item.

---

### 12. **Get Item Image**
- **Endpoint:** `/items/{id}/image`
- **Method:** `GET`
- **Response:** Returns the image of the specified item.
- **Description:** Retrieves the image for an item by its ID.

---

### 13. **Search Items**
- **Endpoint:** `/search/items`
- **Method:** `GET`
- **Query Parameters:**
  - `q`: Search query string
- **Response:**
  ```json
  [
    {
      "id": "integer",
      "name": "string"
    },
    ...
  ]
  ```
- **Description:** Searches for items based on a query string.

---

## Middleware
- **AuthMiddleware:** Validates the JWT token in the `Authorization` header and restricts access to protected endpoints.

## Notes
- Replace `<your-server-address>` and `<port>` with your actual server address and port.
- Ensure that CORS settings allow your frontend to access the API.