stwhite
/
boxes-api
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
boxes-api/api_specification.md

9.8 KiB
Raw Permalink Blame History

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: 
    {
  "username": "string",
  "password": "string"
}
  • Success Response:
    • Code: 200
    • Content: 
      {
  "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: 
      [
  {
    "ID": "number",
    "CreatedAt": "timestamp",
    "UpdatedAt": "timestamp",
    "DeletedAt": "timestamp|null",
    "name": "string"
  }
]

Create Box

  • URL: /boxes
  • Method: POST
  • Auth Required: Yes
  • Request Body: 
    {
  "name": "string"
}
  • Success Response:
    • Code: 200
    • Content: 
      {
  "id": "number",
  "name": "string"
}

Get Box

  • URL: /boxes/{id}
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
  "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: 
      [
  {
    "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: 
    {
  "name": "string",
  "description": "string",
  "box_id": "number"
}
  • Success Response:
    • Code: 200
    • Content: 
      {
  "id": "number",
  "name": "string"
}

Get Item

  • URL: /items/{id}
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
  "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: 
    {
  "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: 
      {
  "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: 
      [
  {
    "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: 
    {
  "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: 
    {
  "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: 
    [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: 
      [
  {
    "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: 
    {
  "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: 
      {
  "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