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:

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

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

  {
    "token": "your_jwt_token"
  }
  

Endpoints:

1. Boxes:

• GET /boxes:

  • Returns a list of all boxes.

  • Response: Array of Box objects

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

• POST /boxes:

  • Creates a new box.

  • Request body: JSON object with the box name

    {
      "name": "New Box"
    }
    

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

    {
      "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

    [
      {
        "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

    {
      "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

    {
      "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