Skip to content

categories-api-reference.md

Latest commit

 

History

History
331 lines (239 loc) · 6.79 KB

categories-api-reference.md

File metadata and controls

331 lines (239 loc) · 6.79 KB
Raw

Categories API Reference

Complete API documentation for the Categories endpoints of the PC Components Store API.

Base URL

http://localhost:8080

Authentication

Most category endpoints require authentication. Include the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get All Categories

GET /api/categories

Retrieve all categories.

Authorization: Public (no authentication required)

Success Response

HTTP/1.1 200 OK
[
  {
    "id": 1,
    "name": "Processors",
    "description": "CPU processors for PCs",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Response Schema (Category)

Field Type Description
id int Category ID
name string Category name (max 100 chars)
description string? Category description (max 500 chars)
createdAt DateTime Creation timestamp

Example Request

curl http://localhost:8080/api/categories

Get Category by ID

GET /api/categories/{id}

Retrieve a specific category by ID.

Authorization: Public (no authentication required)

Path Parameters

Parameter Type Required Description
id int Yes Category ID

Success Response

HTTP/1.1 200 OK
{
  "id": 1,
  "name": "Processors",
  "description": "CPU processors for PCs",
  "createdAt": "2024-01-01T00:00:00Z"
}

Error Responses

Status Code Description
404 Not Found Category does not exist

Example Request

curl http://localhost:8080/api/categories/1

Create Category (Admin Only)

POST /api/categories

Create a new category. Requires admin role.

Authorization: Bearer token with "admin" role

Request Body

{
  "name": "Memory",
  "description": "RAM modules and kits"
}

Request Schema (CreateCategoryRequest)

Field Type Required Description
name string Yes Category name (max 100 chars)
description string? No Category description (max 500 chars)

Success Response

HTTP/1.1 201 Created
{
  "id": 5,
  "name": "Memory",
  "description": "RAM modules and kits",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses

Status Code Description
400 Bad Request Invalid input or validation failed
401 Unauthorized Missing or invalid token
403 Forbidden User is not an admin

Example Request

curl -X POST http://localhost:8080/api/categories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "name": "Memory",
    "description": "RAM modules and kits"
  }'

Update Category (Admin Only)

PUT /api/categories/{id}

Update an existing category. Requires admin role.

Authorization: Bearer token with "admin" role

Path Parameters

Parameter Type Required Description
id int Yes Category ID

Request Body

{
  "name": "RAM & Memory",
  "description": "RAM modules, kits, and memory accessories"
}

Request Schema (UpdateCategoryRequest)

Field Type Required Description
name string Yes Category name (max 100 chars)
description string? No Category description (max 500 chars)

Success Response

HTTP/1.1 200 OK
{
  "id": 5,
  "name": "RAM & Memory",
  "description": "RAM modules, kits, and memory accessories",
  "createdAt": "2024-01-01T00:00:00Z"
}

Error Responses

Status Code Description
400 Bad Request Invalid input
404 Not Found Category does not exist
401 Unauthorized Missing or invalid token
403 Forbidden User is not an admin

Example Request

curl -X PUT http://localhost:8080/api/categories/5 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "name": "RAM & Memory",
    "description": "RAM modules, kits, and memory accessories"
  }'

Delete Category (Admin Only)

DELETE /api/categories/{id}

Delete a category. Requires admin role.

Authorization: Bearer token with "admin" role

Path Parameters

Parameter Type Required Description
id int Yes Category ID

Success Response

HTTP/1.1 204 No Content

Error Responses

Status Code Description
404 Not Found Category does not exist
400 Bad Request Category has associated products
401 Unauthorized Missing or invalid token
403 Forbidden User is not an admin

Example Request

curl -X DELETE http://localhost:8080/api/categories/5 \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Request/Response Models

CreateCategoryRequest

{
  "name": "Memory",
  "description": "RAM modules and kits"
}
Field Type Required Validation
name string Yes Max 100 characters
description string? No Max 500 characters

UpdateCategoryRequest

{
  "name": "RAM & Memory",
  "description": "RAM modules, kits, and memory accessories"
}
Field Type Required Validation
name string Yes Max 100 characters
description string? No Max 500 characters

Category

{
  "id": 1,
  "name": "Processors",
  "description": "CPU processors for PCs",
  "createdAt": "2024-01-01T00:00:00Z"
}
Field Type Description
id int Category ID
name string Category name (max 100 chars)
description string? Category description (max 500 chars)
createdAt DateTime Creation timestamp

Error Responses

Standard Error Format

{
  "error": "Error message description"
}

HTTP Status Codes

Code Description
200 OK Request successful
201 Created Resource created successfully
204 No Content Request successful, no content to return
400 Bad Request Invalid input or validation failed
401 Unauthorized Missing or invalid authentication
403 Forbidden User lacks required permissions
404 Not Found Resource does not exist