.NET API

ASP.NET Core API Documentation

Introduction

This document provides an overview and detailed specifications for the ASP.NET Core Web API. It covers endpoints for managing users, products, orders, and categories, along with authentication and reporting functionalities.

The API follows RESTful principles and uses JSON for request and response bodies. Authentication is handled via JWT tokens.

Base URL: /dotnet/api

Authentication

Endpoints related to user authentication and authorization.

POST
/auth/login

Authenticates a user and returns a JWT token.

Request Body

{
  "username": "string",
  "password": "string"
}

Responses

Status Code Description Schema
200 OK Login successful 
{
  "token": "string",
  "expiresIn": "integer"
}
401 Unauthorized Invalid credentials -
POST
/auth/register

Registers a new user.

Request Body

{
  "username": "string",
  "email": "string",
  "password": "string",
  "firstName": "string",
  "lastName": "string"
}

Responses

Status Code Description Schema
201 Created User registered successfully 
{
  "userId": "string",
  "message": "string"
}
400 Bad Request Invalid input data -
409 Conflict Username or email already exists -

Users

Endpoints for managing user profiles and data.

GET
/users

Retrieves a list of all users. Requires Admin role.

Query Parameters

Name In Type Description Required
role query string Filter users by role (e.g., 'admin', 'customer'). No

Responses

Status Code Description Schema
200 OK List of users 
[
  {
    "userId": "string",
    "username": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "roles": ["string"]
  }
]
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have the required role -
GET
/users/{userId}

Retrieves details for a specific user.

Path Parameters

Name In Type Description Required
userId path string The unique identifier of the user. Yes

Responses

Status Code Description Schema
200 OK User details 
{
  "userId": "string",
  "username": "string",
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "roles": ["string"]
}
401 Unauthorized Authentication token is missing or invalid -
404 Not Found User not found -
PUT
/users/{userId}

Updates an existing user's profile information.

Path Parameters

Name In Type Description Required
userId path string The unique identifier of the user to update. Yes

Request Body

{
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "roles": ["string"] // Optional: Admin only
}

Responses

Status Code Description Schema
200 OK User profile updated successfully 
{
  "message": "User updated successfully."
}
400 Bad Request Invalid input data -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to update this profile -
404 Not Found User not found -
DELETE
/users/{userId}

Deletes a user. Requires Admin role.

Path Parameters

Name In Type Description Required
userId path string The unique identifier of the user to delete. Yes

Responses

Status Code Description Schema
200 OK User deleted successfully 
{
  "message": "User deleted successfully."
}
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to delete users -
404 Not Found User not found -

Products

Endpoints for managing product catalog.

GET
/products

Retrieves a list of all products. Supports filtering and pagination.

Query Parameters

Name In Type Description Required
categoryId query string Filter products by category ID. No
search query string Search products by name or description. No
pageNumber query integer Page number for pagination. No
pageSize query integer Number of items per page. No

Responses

Status Code Description Schema
200 OK List of products 
{
  "items": [
    {
      "productId": "string",
      "name": "string",
      "description": "string",
      "price": "number",
      "stockQuantity": "integer",
      "categoryId": "string"
    }
  ],
  "totalItems": "integer",
  "currentPage": "integer",
  "pageSize": "integer"
}
400 Bad Request Invalid query parameters -
GET
/products/{productId}

Retrieves details for a specific product.

Path Parameters

Name In Type Description Required
productId path string The unique identifier of the product. Yes

Responses

Status Code Description Schema
200 OK Product details 
{
  "productId": "string",
  "name": "string",
  "description": "string",
  "price": "number",
  "stockQuantity": "integer",
  "categoryId": "string"
}
404 Not Found Product not found -
POST
/products

Creates a new product. Requires Admin role.

Request Body

{
  "name": "string",
  "description": "string",
  "price": "number",
  "stockQuantity": "integer",
  "categoryId": "string"
}

Responses

Status Code Description Schema
201 Created Product created successfully 
{
  "productId": "string",
  "message": "Product created successfully."
}
400 Bad Request Invalid input data -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to create products -
PUT
/products/{productId}

Updates an existing product. Requires Admin role.

Path Parameters

Name In Type Description Required
productId path string The unique identifier of the product to update. Yes

Request Body

{
  "name": "string", // Optional
  "description": "string", // Optional
  "price": "number", // Optional
  "stockQuantity": "integer", // Optional
  "categoryId": "string" // Optional
}

Responses

Status Code Description Schema
200 OK Product updated successfully 
{
  "message": "Product updated successfully."
}
400 Bad Request Invalid input data -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to update products -
404 Not Found Product not found -
DELETE
/products/{productId}

Deletes a product. Requires Admin role.

Path Parameters

Name In Type Description Required
productId path string The unique identifier of the product to delete. Yes

Responses

Status Code Description Schema
200 OK Product deleted successfully 
{
  "message": "Product deleted successfully."
}
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to delete products -
404 Not Found Product not found -

Orders

Endpoints for managing customer orders.

GET
/orders

Retrieves a list of orders. Authenticated users can see their own orders, Admins can see all orders.

Query Parameters

Name In Type Description Required
userId query string Filter orders by user ID (Admin only). No
status query string Filter orders by status (e.g., 'Pending', 'Shipped', 'Delivered'). No

Responses

Status Code Description Schema
200 OK List of orders 
[
  {
    "orderId": "string",
    "orderDate": "string (datetime)",
    "totalAmount": "number",
    "status": "string",
    "userId": "string",
    "items": [
        {
            "productId": "string",
            "quantity": "integer",
            "price": "number"
        }
    ]
  }
]
401 Unauthorized Authentication token is missing or invalid -
GET
/orders/{orderId}

Retrieves details for a specific order.

Path Parameters

Name In Type Description Required
orderId path string The unique identifier of the order. Yes

Responses

Status Code Description Schema
200 OK Order details 
{
  "orderId": "string",
  "orderDate": "string (datetime)",
  "totalAmount": "number",
  "status": "string",
  "userId": "string",
  "items": [
      {
          "productId": "string",
          "quantity": "integer",
          "price": "number"
      }
  ]
}
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User is not authorized to view this order -
404 Not Found Order not found -
POST
/orders

Creates a new order.

Request Body

{
  "items": [
    {
      "productId": "string",
      "quantity": "integer"
    }
  ]
}

Responses

Status Code Description Schema
201 Created Order created successfully 
{
  "orderId": "string",
  "message": "Order placed successfully."
}
400 Bad Request Invalid input data, insufficient stock, or invalid product ID -
401 Unauthorized Authentication token is missing or invalid -
PATCH
/orders/{orderId}/status

Updates the status of an order. Requires Admin role.

Path Parameters

Name In Type Description Required
orderId path string The unique identifier of the order. Yes

Request Body

{
  "status": "string" // e.g., "Shipped", "Delivered", "Cancelled"
}

Responses

Status Code Description Schema
200 OK Order status updated successfully 
{
  "message": "Order status updated successfully."
}
400 Bad Request Invalid status value -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to update order status -
404 Not Found Order not found -

Categories

Endpoints for managing product categories.

GET
/categories

Retrieves a list of all product categories.

Responses

Status Code Description Schema
200 OK List of categories 
[
  {
    "categoryId": "string",
    "name": "string",
    "description": "string"
  }
]
POST
/categories

Creates a new category. Requires Admin role.

Request Body

{
  "name": "string",
  "description": "string"
}

Responses

Status Code Description Schema
201 Created Category created successfully 
{
  "categoryId": "string",
  "message": "Category created successfully."
}
400 Bad Request Invalid input data -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to create categories -
409 Conflict Category with this name already exists -
PUT
/categories/{categoryId}

Updates an existing category. Requires Admin role.

Path Parameters

Name In Type Description Required
categoryId path string The unique identifier of the category to update. Yes

Request Body

{
  "name": "string", // Optional
  "description": "string" // Optional
}

Responses

Status Code Description Schema
200 OK Category updated successfully 
{
  "message": "Category updated successfully."
}
400 Bad Request Invalid input data -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to update categories -
404 Not Found Category not found -
DELETE
/categories/{categoryId}

Deletes a category. Requires Admin role.

Path Parameters

Name In Type Description Required
categoryId path string The unique identifier of the category to delete. Yes

Responses

Status Code Description Schema
200 OK Category deleted successfully 
{
  "message": "Category deleted successfully."
}
400 Bad Request Cannot delete category if it has associated products -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to delete categories -
404 Not Found Category not found -

Reports

Endpoints for generating various reports.

GET
/reports/sales

Generates a sales report for a specified period. Requires Admin role.

Query Parameters

Name In Type Description Required
startDate query string (YYYY-MM-DD) The start date for the report. Yes
endDate query string (YYYY-MM-DD) The end date for the report. Yes

Responses

Status Code Description Schema
200 OK Sales report data 
{
  "startDate": "string (YYYY-MM-DD)",
  "endDate": "string (YYYY-MM-DD)",
  "totalSales": "number",
  "numberOfOrders": "integer",
  "topSellingProducts": [
    {
      "productId": "string",
      "name": "string",
      "quantitySold": "integer",
      "revenue": "number"
    }
  ]
}
400 Bad Request Invalid date format or range -
401 Unauthorized Authentication token is missing or invalid -
403 Forbidden User does not have permission to access reports -