[FEAT]: API Endpoint for Getting All Users With Pagination(Super admin)

Description

Implement an API endpoint for retrieving all users with pagination. This endpoint allows authenticated super admins to fetch a paginated list of all users in the system.

Endpoint feature

This endpoint enables authenticated super admins to retrieve a paginated list of all users.
Limited to users with super admin privileges to maintain system security.

Acceptance Criteria

[ ] The endpoint should be accessible at GET /api/v1/users/paginate.
[ ] The endpoint should accept HTTP GET requests.
[ ] The endpoint should support pagination with page and limit query parameters.
[ ] The endpoint should return a paginated list of users with relevant details.
[ ] The endpoint should return a 200 OK status code with the list of users.

Request Example:

GET /api/v1/users?page=1&limit=10&offset=0 Authorization: Bearer

Response Example:

On successful retrieval of users, the API should return a 200 OK status code. The response body should contain a paginated list of users:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "user1",
        "email": "user1@example.com",
        "role": "admin",
        "created_at": "2024-07-22T10:00:00Z"
      },
      {
        "id": 2,
        "username": "user2",
        "email": "user2@example.com",
        "role": "user",
        "created_at": "2024-07-22T11:00:00Z"
      }
    ]
  }
}

Data Validation

Input Validation:

Confirm that a page, limit and offset are all positive numbers
Example: If page or limit are invalid, return a 400 status code with an error message:

{
  "status": "unsuccessful",
  "status_code": 400,
  "message": "Invalid pagination parameters. Page and limit must be positive integers."
}

Output Validation

Ensure the response format is correct and includes appropriate status codes, messages, and pagination metadata.
If there are no users for the given page, return an empty array in the users field with correct pagination metadata.

Authentication and Authorization

Authentication

Verify that the user is authenticated before allowing access to the endpoint.
Example: Use middleware to check for a valid authentication token.

Authorization

Ensure that only super admin users can access this endpoint.
Example: Check user roles or permissions to confirm super admin authorization.

Error Handling

Error Responses

Define error responses for common failure scenarios.

Example: If the user is not authorized, return a 403 Forbidden status code with an error message:

{
"status": "unsuccessful",
"status_code": 403,
"message": "Access denied. Super admin privileges required."
}

Edge Cases

Consider edge cases such as database connection issues, corrupted user data, or requests for pages beyond available data.
Example: Handle scenarios where the requested page number exceeds the total number of pages.

Documentation

API Documentation:

Document the endpoint in the API documentation with request and response examples using the standard OpenAPI 3.1.0 standard.

Technical Notes:

Include details on the authentication mechanism.

Testing Requirements

Unit Tests:

Write unit tests to validate the retrieval logic, pagination calculations, and authorization checks.
Write tests for all error cases.

Integration Tests

Ensure end-to-end functionality is tested with integration tests, including various pagination scenarios, authentication, and authorization flows.

Dependencies and Impact

Dependencies

Ensure the user authentication middleware and super-admin middleware is up and running

Impact Analysis

Assess the potential impact on other features or components, ensuring that existing functionality is not disrupted.
Consider the impact on API consumers who may need to update their integration to handle paginated responses.

hngprojects / hng_boilerplate_expressjs