[FEAT]: Add Filter to GET Request for Product Endpoint

[PeterOyelegbin]

Is your feature request related to a problem? Please describe.
Currently, the product endpoint GET /api/products retrieves all products without any filtering options. This becomes problematic when users need to fetch specific products based on criteria such as category. For example, a user might want to retrieve only products in a particular category. Without filtering, the client has to retrieve and manually filter all products, which is inefficient and increases unnecessary data transfer.

---

Describe the solution you'd like
I propose adding query parameters to the GET /api/products endpoint to allow filtering based on category (e.g., ?category=CATEGORY_NAME).
Example request:

GET /api/products?category=CATEGORY_NAME

This would return only products in that particular category

---

Additional context

• This feature would align with RESTful API best practices, where query parameters are commonly used for filtering, sorting, and pagination.
• The implementation should ensure backward compatibility so that existing clients using the endpoint without filters continue to work as expected.
• Documentation should be updated to include examples of how to use the new filtering options.

[joboy-dev]

Not very detailed

[PeterOyelegbin]

Please clarify what details are needed to add to issues creation so I can update it accordingly.

[joboy-dev]

Look at approved issues and you'll see what is missing

[PeterOyelegbin]

Description

Update the GET /api/v1/products endpoint to include a filter by category parameter, allowing users to retrieve products based on their category of interest.

Acceptance Criteria

1. The endpoint should support the following query parameters:

• limit: Number of items to return per page.
• skip: Number of items to skip (for pagination).
• category: Category name to filter products by.

2. The endpoint must remain PROTECTED, requiring authentication via a valid access token.
3. Backward compatibility must be maintained so that existing clients using the endpoint without the category filter continue to work as expected.
4. The endpoint should return appropriate success or failure responses with relevant status codes and messages.

Purpose

• To enable users to query products relevant to their category of interest while maintaining the existing functionality for unfiltered requests.

Requirements

• Update the server-side logic to filter products based on the category query parameter.
• Ensure the endpoint can still retrieve all products when the category parameter is not provided.
• Write unit tests to verify the correctness and accuracy of the filtering logic.

Expected Outcome

• Users should be able to filter products by category while ensuring proper authorization checks.
• The endpoint should continue to function as expected for clients not using the category filter.

Tasks

• Update the GET /api/v1/products endpoint to accept and process the category query parameter.
• Write unit tests to cover the following scenarios:
  • Successful retrieval of products filtered by category.
  • Successful retrieval of all products when no category filter is provided.
  • Unauthorized access attempts (missing or invalid access token).
  • Edge cases (e.g., invalid category name, empty results).

Example Request [With Auth Token]

GET Request:

curl -X GET {rootdomain}/api/v1/products?limit=10&skip=1&category=CATEGORY_NAME \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response (Success):

{
    "status_code": 200,
    "success": true,
    "message": "Successfully fetched items",
    "data": {
        "pages": 0,
        "total": 0,
        "skip": 1,
        "limit": 10,
        "items": []
    }
}

Example Response (Error - Unauthorized):

{
  "status": false,
  "status_code": 401,
  "message": "Not authorized"
}

Testing

1. Write unit tests for the following scenarios:

• Filtering products by a valid category.
• Retrieving all products without a category filter.
• Handling invalid or non-existent categories.
• Unauthorized access attempts.

2. Ensure all tests pass and cover edge cases.