boxes-api/api_specification.md

# Boxes API Specification

## Base URL
`/api/v1`

## Authentication
- All endpoints except `/login` require JWT authentication
- JWT token must be provided in the Authorization header as `Bearer <token>`
- Tokens expire after 24 hours

## Endpoints

### Authentication

#### Login
- **URL**: `/login`
- **Method**: `POST`
- **Auth Required**: No
- **Request Body**:
  ```json
  {
    "username": "string",
    "password": "string"
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "token": "string"
    }
    ```
- **Error Responses**:
  - **Code**: 401 UNAUTHORIZED
  - **Content**: "Invalid username or password"

### Boxes

#### Get All Boxes
- **URL**: `/boxes`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    [
      {
        "ID": "number",
        "CreatedAt": "timestamp",
        "UpdatedAt": "timestamp",
        "DeletedAt": "timestamp|null",
        "name": "string"
      }
    ]
    ```

#### Create Box
- **URL**: `/boxes`
- **Method**: `POST`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  {
    "name": "string"
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "id": "number",
      "name": "string"
    }
    ```

#### Get Box
- **URL**: `/boxes/{id}`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "ID": "number",
      "CreatedAt": "timestamp",
      "UpdatedAt": "timestamp",
      "DeletedAt": "timestamp|null",
      "name": "string"
    }
    ```
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Box not found"

#### Delete Box
- **URL**: `/boxes/{id}`
- **Method**: `DELETE`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 204 NO CONTENT
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Box not found"

### Items

#### Get All Items
- **URL**: `/items`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    [
      {
        "ID": "number",
        "CreatedAt": "timestamp",
        "UpdatedAt": "timestamp",
        "DeletedAt": "timestamp|null",
        "name": "string",
        "description": "string",
        "box_id": "number",
        "image_path": "string",
        "tags": [
          {
            "ID": "number",
            "name": "string",
            "description": "string",
            "color": "string"
          }
        ]
      }
    ]
    ```

#### Create Item
- **URL**: `/items`
- **Method**: `POST`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  {
    "name": "string",
    "description": "string",
    "box_id": "number"
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "id": "number",
      "name": "string"
    }
    ```

#### Get Item
- **URL**: `/items/{id}`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "ID": "number",
      "CreatedAt": "timestamp",
      "UpdatedAt": "timestamp",
      "DeletedAt": "timestamp|null",
      "name": "string",
      "description": "string",
      "box_id": "number",
      "image_path": "string",
      "tags": [
        {
          "ID": "number",
          "name": "string",
          "description": "string",
          "color": "string"
        }
      ]
    }
    ```
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Item not found"

#### Update Item
- **URL**: `/items/{id}`
- **Method**: `PUT`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  {
    "name": "string",
    "description": "string",
    "box_id": "number"
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**: Updated item object
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Item not found"

#### Delete Item
- **URL**: `/items/{id}`
- **Method**: `DELETE`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 204 NO CONTENT
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Item not found"

#### Get Items in Box
- **URL**: `/boxes/{id}/items`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**: Array of item objects
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Items not found"

#### Search Items
- **URL**: `/search/items`
- **Method**: `GET`
- **Auth Required**: Yes
- **Query Parameters**:
  - `q`: Search query string
- **Success Response**:
  - **Code**: 200
  - **Content**: Array of matching item objects
- **Error Response**:
  - **Code**: 400 BAD REQUEST
  - **Content**: "Search query is required"

### Item Images

#### Upload Item Image
- **URL**: `/items/{id}/upload`
- **Method**: `POST`
- **Auth Required**: Yes
- **Content-Type**: `multipart/form-data`
- **Form Parameters**:
  - `image`: File upload
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "imagePath": "string"
    }
    ```
- **Error Responses**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Item not found"
  - **Code**: 400 BAD REQUEST
  - **Content**: "Unable to parse form"

#### Get Item Image
- **URL**: `/items/{id}/image`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**: Image file
- **Note**: Returns default image if no image is found

### Tags

#### Get All Tags
- **URL**: `/tags`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    [
      {
        "ID": "number",
        "CreatedAt": "timestamp",
        "UpdatedAt": "timestamp",
        "DeletedAt": "timestamp|null",
        "name": "string",
        "description": "string",
        "color": "string" // hex color code
      }
    ]
    ```

#### Create Tag
- **URL**: `/tags`
- **Method**: `POST`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  {
    "name": "string",
    "description": "string",
    "color": "string" // hex color code, optional
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**: Created tag object
- **Error Responses**:
  - **Code**: 400 BAD REQUEST
  - **Content**: "Tag name is required"
  - **Code**: 409 CONFLICT
  - **Content**: "Tag name already exists"

#### Update Tag
- **URL**: `/tags/{id}`
- **Method**: `PUT`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  {
    "name": "string",
    "description": "string",
    "color": "string"
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**: Updated tag object
- **Error Responses**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Tag not found"
  - **Code**: 409 CONFLICT
  - **Content**: "Tag name already exists"

#### Delete Tag
- **URL**: `/tags/{id}`
- **Method**: `DELETE`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 204 NO CONTENT
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Tag not found"

### Item Tags

#### Add Tags to Item
- **URL**: `/items/{id}/tags`
- **Method**: `POST`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  [1, 2, 3]  // Array of tag IDs
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**: Updated item object with tags
- **Error Responses**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Item not found"
  - **Code**: 400 BAD REQUEST
  - **Content**: "Tag {id} not found"

#### Remove Tag from Item
- **URL**: `/items/{id}/tags/{tagId}`
- **Method**: `DELETE`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 204 NO CONTENT
- **Error Responses**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Item not found" or "Tag not found"

#### Get Items by Tag
- **URL**: `/tags/{id}/items`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    [
      {
        "ID": "number",
        "CreatedAt": "timestamp",
        "UpdatedAt": "timestamp",
        "DeletedAt": "timestamp|null",
        "name": "string",
        "description": "string",
        "box_id": "number",
        "image_path": "string",
        "tags": [
          {
            "ID": "number",
            "name": "string",
            "description": "string",
            "color": "string"
          }
        ]
      }
    ]
    ```
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "Tag not found"

### Admin Endpoints

#### Get All Users
- **URL**: `/admin/user`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**: Array of user objects

#### Create User
- **URL**: `/admin/user`
- **Method**: `POST`
- **Auth Required**: Yes
- **Request Body**:
  ```json
  {
    "username": "string",
    "password": "string",
    "email": "string"
  }
  ```
- **Success Response**:
  - **Code**: 200
  - **Content**: Created user object

#### Get User
- **URL**: `/admin/user/{id}`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**: User object
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "User not found"

#### Delete User
- **URL**: `/admin/user/{id}`
- **Method**: `DELETE`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 204 NO CONTENT
- **Error Response**:
  - **Code**: 404 NOT FOUND
  - **Content**: "User not found"

#### Backup Database
- **URL**: `/admin/db`
- **Method**: `GET`
- **Auth Required**: Yes
- **Success Response**:
  - **Code**: 200
  - **Content**: Database file

#### Restore Database
- **URL**: `/admin/db`
- **Method**: `POST`
- **Auth Required**: Yes
- **Content-Type**: `multipart/form-data`
- **Form Parameters**:
  - `database`: Database file
- **Success Response**:
  - **Code**: 200
  - **Content**:
    ```json
    {
      "message": "Database restored successfully"
    }
    ```

## Error Responses
All endpoints may return these common errors:
- **401 Unauthorized**: Missing or invalid authentication token
- **500 Internal Server Error**: Server-side error