Catalog API Reference - AspNetRun Microservices

Base URL

http://localhost:5001

Authentication

The Catalog service currently does not require authentication. In production, integrate with your API Gateway for authentication.

Endpoints

Get Products

Retrieve a paginated list of products.

GET /products

Query Parameters

PageNumber

integer

default:"1"

The page number to retrieve (1-based index)

PageSize

integer

default:"10"

Number of products per page

Response

products

array

List of product objects

Show Product Object

string

Unique product identifier (GUID)

name

string

Product name

category

array

List of category strings

description

string

Product description

imageFile

string

Image filename or URL

price

number

Product price (decimal)

Example Request

curl -X GET "http://localhost:5001/products?PageNumber=1&PageSize=10"

Example Response

{
  "products": [
    {
      "id": "5334c996-8457-4cf0-815c-ed2b77c4ff61",
      "name": "IPhone X",
      "category": ["Smart Phone"],
      "description": "This phone is the company's biggest change to its flagship smartphone in years. It includes a borderless.",
      "imageFile": "product-1.png",
      "price": 950.00
    },
    {
      "id": "c67d6323-e8b1-4bdf-9a75-b0d0d2e7e914",
      "name": "Samsung 10",
      "category": ["Smart Phone"],
      "description": "This phone is the company's biggest change to its flagship smartphone in years. It includes a borderless.",
      "imageFile": "product-2.png",
      "price": 840.00
    }
  ]
}

Get Product By ID

Retrieve a single product by its ID.

GET /products/{id}

Path Parameters

string

required

Product ID (GUID)

Response

product

object

Show Product Object

string

Unique product identifier (GUID)

name

string

Product name

category

array

List of category strings

description

string

Product description

imageFile

string

Image filename or URL

price

number

Product price (decimal)

Example Request

curl -X GET "http://localhost:5001/products/5334c996-8457-4cf0-815c-ed2b77c4ff61"

Example Response

{
  "product": {
    "id": "5334c996-8457-4cf0-815c-ed2b77c4ff61",
    "name": "IPhone X",
    "category": ["Smart Phone"],
    "description": "This phone is the company's biggest change to its flagship smartphone in years. It includes a borderless.",
    "imageFile": "product-1.png",
    "price": 950.00
  }
}

Error Responses

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Product with id '5334c996-8457-4cf0-815c-ed2b77c4ff61' was not found."
}

Get Products By Category

Retrieve all products in a specific category.

GET /products/category/{category}

Path Parameters

category

string

required

Category name (case-sensitive)

Response

products

array

List of product objects matching the category

Show Product Object

string

Unique product identifier (GUID)

name

string

Product name

category

array

List of category strings

description

string

Product description

imageFile

string

Image filename or URL

price

number

Product price (decimal)

Example Request

curl -X GET "http://localhost:5001/products/category/Smart%20Phone"

Example Response

{
  "products": [
    {
      "id": "5334c996-8457-4cf0-815c-ed2b77c4ff61",
      "name": "IPhone X",
      "category": ["Smart Phone"],
      "description": "This phone is the company's biggest change to its flagship smartphone in years. It includes a borderless.",
      "imageFile": "product-1.png",
      "price": 950.00
    },
    {
      "id": "c67d6323-e8b1-4bdf-9a75-b0d0d2e7e914",
      "name": "Samsung 10",
      "category": ["Smart Phone"],
      "description": "This phone is the company's biggest change to its flagship smartphone in years. It includes a borderless.",
      "imageFile": "product-2.png",
      "price": 840.00
    }
  ]
}

Create Product

Create a new product in the catalog.

POST /products

Request Body

name

string

required

Product name (required, non-empty)

category

array

required

List of category strings (required, at least one category)

description

string

required

Product description

imageFile

string

required

Image filename or URL (required, non-empty)

price

number

required

Product price (must be greater than 0)

Response

string

The newly created product’s ID (GUID)

Example Request

curl -X POST "http://localhost:5001/products" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "iPhone 15 Pro",
    "category": ["Smart Phone", "Electronics"],
    "description": "Latest iPhone model with advanced features",
    "imageFile": "iphone-15-pro.png",
    "price": 1199.00
  }'

Example Response

201 - Created

{
  "id": "a1234567-89ab-cdef-0123-456789abcdef"
}

The response includes a Location header:

Location: /products/a1234567-89ab-cdef-0123-456789abcdef

Validation Rules

name: Required, cannot be empty
category: Required, must contain at least one category
imageFile: Required, cannot be empty
price: Required, must be greater than 0

Error Responses

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": ["Name is required"],
    "Price": ["Price must be greater than 0"]
  }
}

Update Product

Update an existing product.

PUT /products

Request Body

string

required

Product ID (GUID) to update

name

string

required

Product name (2-150 characters)

category

array

required

List of category strings

description

string

required

Product description

imageFile

string

required

Image filename or URL

price

number

required

Product price (must be greater than 0)

Response

isSuccess

boolean

Indicates whether the update was successful

Example Request

curl -X PUT "http://localhost:5001/products" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "5334c996-8457-4cf0-815c-ed2b77c4ff61",
    "name": "iPhone X - Updated",
    "category": ["Smart Phone", "Premium"],
    "description": "Updated description for iPhone X",
    "imageFile": "product-1-updated.png",
    "price": 899.00
  }'

Example Response

200 - OK

{
  "isSuccess": true
}

Validation Rules

id: Required, cannot be empty
name: Required, must be between 2 and 150 characters
price: Required, must be greater than 0

Error Responses

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Product with id '5334c996-8457-4cf0-815c-ed2b77c4ff61' was not found."
}

Delete Product

Delete a product from the catalog.

DELETE /products/{id}

Path Parameters

string

required

Product ID (GUID) to delete

Response

isSuccess

boolean

Indicates whether the deletion was successful

Example Request

curl -X DELETE "http://localhost:5001/products/5334c996-8457-4cf0-815c-ed2b77c4ff61"

Example Response

200 - OK

{
  "isSuccess": true
}

Error Responses

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Id": ["Product ID is required"]
  }
}

Health Check

Check the health status of the Catalog service and its dependencies.

GET /health

Response

status

string

Overall health status: Healthy, Degraded, or Unhealthy

results

object

Detailed health check results for each dependency

Show Results Object

npgsql

object

PostgreSQL database health check result

Show Database Check

status

string

Database connection status

description

string

Additional details about the health check

data

object

Additional metadata

Example Request

curl -X GET "http://localhost:5001/health"

Example Response

200 - Healthy

{
  "status": "Healthy",
  "results": {
    "npgsql": {
      "status": "Healthy",
      "description": "Database connection is healthy",
      "data": {}
    }
  }
}

503 - Unhealthy

{
  "status": "Unhealthy",
  "results": {
    "npgsql": {
      "status": "Unhealthy",
      "description": "Unable to connect to database",
      "data": {
        "exception": "Connection refused"
      }
    }
  }
}

Error Handling

The Catalog service uses standard HTTP status codes and returns problem details compliant with RFC 7807.

Status Codes

Status Code	Description
200	OK - Request succeeded
201	Created - Resource created successfully
400	Bad Request - Validation error or malformed request
404	Not Found - Resource not found
500	Internal Server Error - Unexpected server error
503	Service Unavailable - Service or dependency is down

Problem Details Format

All errors follow the RFC 7807 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "See errors for details.",
  "errors": {
    "Name": ["Name is required"],
    "Price": ["Price must be greater than 0"]
  }
}

Rate Limiting

Rate limiting is not implemented in the Catalog service itself but should be configured at the API Gateway level.

Versioning

The current API version is v1. Versioning strategy may be implemented in future releases.

Catalog Service

Basket Service

Discount Service

Ordering Service

​Base URL

​Authentication

​Endpoints

​Get Products

​Query Parameters

​Response

​Example Request

​Example Response

​Get Product By ID

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Get Products By Category

​Path Parameters

​Response

​Example Request

​Example Response

​Create Product

​Request Body

​Response

​Example Request

​Example Response

​Validation Rules

​Error Responses

​Update Product

​Request Body

​Response

​Example Request

​Example Response

​Validation Rules

​Error Responses

​Delete Product

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Health Check

​Response

​Example Request

​Example Response

​Error Handling

​Status Codes

​Problem Details Format

​Rate Limiting

​Versioning

Build docs developers (and LLMs) love

Base URL

Authentication

Endpoints

Get Products

Query Parameters

Response

Example Request

Example Response

Get Product By ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Get Products By Category

Path Parameters

Response

Example Request

Example Response

Create Product

Request Body

Response

Example Request

Example Response

Validation Rules

Error Responses

Update Product

Request Body

Response

Example Request

Example Response

Validation Rules

Error Responses

Delete Product

Path Parameters

Response

Example Request

Example Response

Error Responses

Health Check

Response

Example Request

Example Response

Error Handling

Status Codes

Problem Details Format

Rate Limiting

Versioning