Toolshop API Documentation

Toolshop API Documentation (v5.0.0)

Swagger Documentation: https://api.practicesoftwaretesting.com/docs?api-docs.json

Toolshop REST API technical description. This is a comprehensive e-commerce API supporting operations for Brands, Products, Carts, Users, and more.

Prepared by:

Md. Ebrahim Hossain

SQA Engineer at Achieve Test Prep (Newark, US)

Source API: practicesoftwaretesting.com

View LinkedIn

Base URL

The primary endpoint for all API calls is:


                        https://api.practicesoftwaretesting.com

Brand Operations

1. Store New Brand

POST /brands Status Code: 201

Request Body (Brand Object)

{
  "name": "PowerTools Inc."
}

Response (201 Created)

HTTP/1.1 201 Created
{
  "id": 101,
  "name": "PowerTools Inc.",
  "slug": "powertools-inc"
}

2. Retrieve All Brands / Search

GET /brands | /brands/search?query={q} Status Code: 200

Request Example (Search)

GET /brands/search?query=power HTTP/1.1

Response (200 OK)

HTTP/1.1 200 OK
[
  {
    "id": 101,
    "name": "PowerTools Inc."
  }
]

3. Update Brand (PUT/PATCH)

PUT PATCH /brands/{brandId} Status Code: 200

Request Body (PUT Example)

{
  "name": "PowerTools Ltd."
}

Response (200 OK)

HTTP/1.1 200 OK
{
  "id": 101,
  "name": "PowerTools Ltd.",
  "slug": "powertools-ltd"
}

Product Operations

1. Retrieve All Products

GET /products Status Code: 200

Request Example (Pagination)

GET /products?page=1&pageSize=10 HTTP/1.1

Response (200 OK)

HTTP/1.1 200 OK
{
  "items": [
    {
      "id": 1,
      "name": "Hammer A1",
      "price": 12.50
    }
    ...
  ],
  "totalPages": 5
}

2. Store New Product

POST /products Status Code: 201

Request Body (Product Object)

{
  "name": "New Drill Model X",
  "price": 89.99,
  "brandId": 101,
  "categoryId": 20
}

Response (201 Created)

HTTP/1.1 201 Created
{
  "id": 500,
  "name": "New Drill Model X",
  ... full product details ...
}

3. Delete Specific Product

DELETE /products/{productId} Status Code: 204

Request

DELETE /products/500 HTTP/1.1

Response (204 No Content)

HTTP/1.1 204 No Content

# Success: No content returned.

Cart Operations

1. Create New Cart

POST /carts Status Code: 201

Request

No body required for creation.

POST /carts HTTP/1.1

Response (201 Created)

HTTP/1.1 201 Created
{
  "id": C12345,
  "items": []
}

2. Add Item to Cart

POST /carts/{cartId} Status Code: 200

Request Body (Item Details)

{
  "productId": 1,
  "quantity": 2
}

Response (200 OK)

HTTP/1.1 200 OK
{
  "id": C12345,
  "items": [
    {
      "productId": 1,
      "quantity": 2
    }
  ]
}

3. Delete Product from Cart

DELETE /carts/{cartId}/product/{productId} Status Code: 200

Request

DELETE /carts/C12345/product/1 HTTP/1.1

Response (200 OK - Updated Cart)

HTTP/1.1 200 OK
{
  "id": "C12345",
  "items": []
}

Category Operations

1. Retrieve Categories (Tree Structure)

GET /categories/tree Status Code: 200

Request

GET /categories/tree HTTP/1.1

Response (200 OK)

HTTP/1.1 200 OK
[
  {
    "id": 1,
    "name": "Hardware",
    "children": [
      {
        "id": 10,
        "name": "Drills"
      }
    ]
  }
]

User & Authentication Operations

1. Register New User

POST /users/register Status Code: 201

Request Body (Registration)

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@test.com",
  "password": "Password123!"
}

Response (201 Created)

HTTP/1.1 201 Created
{
  "id": 9001,
  "firstName": "Jane",
  "token": "eyJhbGciOiJIUzI1NiI..."
}

2. Login Customer

POST /users/login Status Code: 200

Request Body (Credentials)

{
  "email": "jane.doe@test.com",
  "password": "Password123!"
}

Response (200 OK)

HTTP/1.1 200 OK
{
  "token": "eyJhbGciOiJIUzI1NiI...",
  "firstName": "Jane",
  "email": "jane.doe@test.com"
}

3. Retrieve Current User (/users/me)

GET /users/me Status Code: 200

Requires `Authorization: Bearer {Token}` header.

Request Example

GET /users/me HTTP/1.1
Host: api.practicesoftwaretesting.com
Authorization: Bearer {TOKEN}

Response (200 OK)

HTTP/1.1 200 OK
{
  "id": 9001,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@test.com"
}

Report & Analytics Operations

All report endpoints typically require authorization.

1. Total Sales Per Country

GET /reports/total-sales-per-country Status Code: 200

Request

GET /reports/total-sales-per-country HTTP/1.1

Response (200 OK)

HTTP/1.1 200 OK
[
  {
    "country": "USA",
    "totalSales": 15498.50
  },
  {
    "country": "Canada",
    "totalSales": 5100.99
  }
]

2. Top 10 Purchased Products

GET /reports/top10-purchased-products Status Code: 200

Request

GET /reports/top10-purchased-products HTTP/1.1

Response (200 OK)

HTTP/1.1 200 OK
[
  {
    "productName": "Adjustable Wrench",
    "unitsSold": 550
  },
  {
    "productName": "Safety Goggles",
    "unitsSold": 480
  }
  ... up to 10 items ...
]

Other Core Modules

4. Category Management

The API provides endpoints for full CRUD operations on product categories, including retrieving the nested category tree structure (`/categories/tree`).

GET /categories POST /categories PUT /categories/{id} DELETE /categories/{id}

5. Contact Messaging

Handles customer support messages, replies, and file attachments. Key operations include `POST /messages` and `POST /messages/{id}/reply`.

POST /messages GET /messages/{id} PUT /messages/{id}/status

6. Invoice Management

Comprehensive handling of sales invoices, including guest checkout, PDF generation/download (`/invoices/{invoice_number}/download-pdf`), and status updates.

POST /invoices GET /invoices/{id} PUT /invoices/{id} PATCH /invoices/{id}

QA Mirror

Endpoints