Skip to content

products-api-reference.md

Latest commit

 

History

History
506 lines (392 loc) · 11.8 KB

products-api-reference.md

File metadata and controls

506 lines (392 loc) · 11.8 KB
Raw

Products API Reference

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

Base URL

http://localhost:8080

Authentication

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

Authorization: Bearer YOUR_JWT_TOKEN

Get All Products

GET /api/products

Retrieve all products with category information.

Authorization: Public (no authentication required)

Success Response

HTTP/1.1 200 OK
[
  {
    "id": 1,
    "name": "Intel Core i7-12700K",
    "description": "12th Gen Intel Core processor",
    "price": 409.99,
    "stockQuantity": 25,
    "sku": "INT-i7-12700K",
    "imageUrl": "https://example.com/images/i7-12700k.jpg",
    "categoryId": 1,
    "categoryName": "Processors",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Response Schema (ProductDto)

Field Type Description
id int Product ID
name string Product name (max 200 chars)
description string? Product description (max 1000 chars)
price decimal Product price
stockQuantity int Available stock
sku string? Stock keeping unit (max 100 chars)
imageUrl string? Product image URL (max 200 chars)
categoryId int Category ID
categoryName string? Category name
createdAt DateTime Creation timestamp

Example Request

curl http://localhost:8080/api/products

Get Product by ID

GET /api/products/{id}

Retrieve a specific product by ID.

Authorization: Public (no authentication required)

Path Parameters

Parameter Type Required Description
id int Yes Product ID

Success Response

HTTP/1.1 200 OK
{
  "id": 1,
  "name": "Intel Core i7-12700K",
  "description": "12th Gen Intel Core processor",
  "price": 409.99,
  "stockQuantity": 25,
  "sku": "INT-i7-12700K",
  "imageUrl": "https://example.com/images/i7-12700k.jpg",
  "categoryId": 1,
  "categoryName": "Processors",
  "createdAt": "2024-01-01T00:00:00Z"
}

Error Responses

Status Code Description
404 Not Found Product does not exist

Example Request

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

Get Products by Category

GET /api/products/category/{categoryId}

Retrieve all products in a specific category.

Authorization: Public (no authentication required)

Path Parameters

Parameter Type Required Description
categoryId int Yes Category ID

Success Response

HTTP/1.1 200 OK
[
  {
    "id": 1,
    "name": "Intel Core i7-12700K",
    "description": "12th Gen Intel Core processor",
    "price": 409.99,
    "stockQuantity": 25,
    "sku": "INT-i7-12700K",
    "imageUrl": "https://example.com/images/i7-12700k.jpg",
    "categoryId": 1,
    "categoryName": "Processors",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Example Request

curl http://localhost:8080/api/products/category/1

Search Products

GET /api/products/search

Search products by name or description.

Authorization: Public (no authentication required)

Query Parameters

Parameter Type Required Description
searchTerm string Yes Search term to match

Success Response

HTTP/1.1 200 OK
[
  {
    "id": 5,
    "name": "NVIDIA GeForce RTX 3080",
    "description": "High-performance graphics card",
    "price": 699.99,
    "stockQuantity": 10,
    "sku": "NVD-RTX3080",
    "imageUrl": "https://example.com/images/rtx3080.jpg",
    "categoryId": 2,
    "categoryName": "Graphics Cards",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

Example Request

curl "http://localhost:8080/api/products/search?searchTerm=graphics"

Create Product (Admin Only)

POST /api/products

Create a new product. Requires admin role.

Authorization: Bearer token with "admin" role

Request Body

{
  "name": "AMD Ryzen 9 5950X",
  "description": "16-core, 32-thread processor",
  "price": 799.99,
  "stockQuantity": 15,
  "sku": "AMD-R9-5950X",
  "imageUrl": "https://example.com/images/5950x.jpg",
  "categoryId": 1
}

Request Schema (CreateProductRequest)

Field Type Required Description
name string Yes Product name (max 200 chars)
description string? No Product description (max 1000 chars)
price decimal Yes Product price
stockQuantity int Yes Initial stock quantity
sku string? No Stock keeping unit (max 100 chars)
imageUrl string? No Product image URL (max 200 chars)
categoryId int Yes Category ID

Success Response

HTTP/1.1 201 Created
{
  "id": 10,
  "name": "AMD Ryzen 9 5950X",
  "description": "16-core, 32-thread processor",
  "price": 799.99,
  "stockQuantity": 15,
  "sku": "AMD-R9-5950X",
  "imageUrl": "https://example.com/images/5950x.jpg",
  "categoryId": 1,
  "categoryName": "Processors",
  "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/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "name": "AMD Ryzen 9 5950X",
    "description": "16-core, 32-thread processor",
    "price": 799.99,
    "stockQuantity": 15,
    "sku": "AMD-R9-5950X",
    "imageUrl": "https://example.com/images/5950x.jpg",
    "categoryId": 1
  }'

Update Product (Admin Only)

PUT /api/products/{id}

Update an existing product. Requires admin role.

Authorization: Bearer token with "admin" role

Path Parameters

Parameter Type Required Description
id int Yes Product ID

Request Body

{
  "name": "AMD Ryzen 9 7950X",
  "description": "16-core, 32-thread processor, 5nm",
  "price": 699.99,
  "stockQuantity": 20,
  "sku": "AMD-R9-7950X",
  "imageUrl": "https://example.com/images/7950x.jpg",
  "categoryId": 1
}

Request Schema (UpdateProductRequest)

Field Type Required Description
name string? No Product name (max 200 chars)
description string? No Product description (max 1000 chars)
price decimal? No Product price
stockQuantity int? No Stock quantity
sku string? No Stock keeping unit (max 100 chars)
imageUrl string? No Product image URL (max 200 chars)
categoryId int? No Category ID

Success Response

HTTP/1.1 200 OK
{
  "id": 10,
  "name": "AMD Ryzen 9 7950X",
  "description": "16-core, 32-thread processor, 5nm",
  "price": 699.99,
  "stockQuantity": 20,
  "sku": "AMD-R9-7950X",
  "imageUrl": "https://example.com/images/7950x.jpg",
  "categoryId": 1,
  "categoryName": "Processors",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses

Status Code Description
400 Bad Request Invalid input
404 Not Found Product 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/products/10 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "name": "AMD Ryzen 9 7950X",
    "description": "16-core, 32-thread processor, 5nm",
    "price": 699.99,
    "stockQuantity": 20,
    "sku": "AMD-R9-7950X",
    "imageUrl": "https://example.com/images/7950x.jpg",
    "categoryId": 1
  }'

Delete Product (Admin Only)

DELETE /api/products/{id}

Delete a product. Requires admin role.

Authorization: Bearer token with "admin" role

Path Parameters

Parameter Type Required Description
id int Yes Product ID

Success Response

HTTP/1.1 204 No Content

Error Responses

Status Code Description
404 Not Found Product does not exist
401 Unauthorized Missing or invalid token
403 Forbidden User is not an admin

Example Request

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

Request/Response Models

CreateProductRequest

{
  "name": "AMD Ryzen 9 5950X",
  "description": "16-core, 32-thread processor",
  "price": 799.99,
  "stockQuantity": 15,
  "sku": "AMD-R9-5950X",
  "imageUrl": "https://example.com/images/5950x.jpg",
  "categoryId": 1
}
Field Type Required Validation
name string Yes Max 200 characters
description string? No Max 1000 characters
price decimal Yes Positive value
stockQuantity int Yes Non-negative value
sku string? No Max 100 characters
imageUrl string? No Max 200 characters
categoryId int Yes Must exist

UpdateProductRequest

{
  "name": "AMD Ryzen 9 7950X",
  "description": "16-core, 32-thread processor, 5nm",
  "price": 699.99,
  "stockQuantity": 20,
  "sku": "AMD-R9-7950X",
  "imageUrl": "https://example.com/images/7950x.jpg",
  "categoryId": 1
}
Field Type Required Validation
name string? No Max 200 characters
description string? No Max 1000 characters
price decimal? No Positive value
stockQuantity int? No Non-negative value
sku string? No Max 100 characters
imageUrl string? No Max 200 characters
categoryId int? No Must exist

ProductDto

{
  "id": 1,
  "name": "Intel Core i7-12700K",
  "description": "12th Gen Intel Core processor",
  "price": 409.99,
  "stockQuantity": 25,
  "sku": "INT-i7-12700K",
  "imageUrl": "https://example.com/images/i7-12700k.jpg",
  "categoryId": 1,
  "categoryName": "Processors",
  "createdAt": "2024-01-01T00:00:00Z"
}
Field Type Description
id int Product ID
name string Product name (max 200 chars)
description string? Product description (max 1000 chars)
price decimal Product price
stockQuantity int Available stock
sku string? Stock keeping unit (max 100 chars)
imageUrl string? Product image URL (max 200 chars)
categoryId int Category ID
categoryName string? Category name
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