nipun221 / heliverse

The MERN stack powers our Admin Dashboard, a dynamic and efficient solution for streamlined management. With MongoDB, Express.js, React, and Node.js, it ensures a seamless user experience, providing comprehensive control and insights in a responsive and intuitive interface.

OAdmin

Website is hosted at = https://heliverse-phi.vercel.app/

Server is hosted at = https://heliverse-server-v1.onrender.com/

OAdmin API Documentation

Overview

The OAdmin API provides endpoints to manage a collection of mock user data. Users can be retrieved, created, updated, and deleted. The API supports various queries such as pagination, searching, and filtering based on different parameters.

Base URL

The base URL for the API is http://localhost:{PORT}, where {PORT} is the port number specified during the server setup.

Authentication

To access certain endpoints, authentication is required. Users need to include a valid JWT (JSON Web Token) in the Authorization header of the HTTP request.

JWT Generation

A JWT can be generated by logging in through the /api/users/login endpoint. The generated token must then be included in the header for subsequent authenticated requests.

Endpoints

User Registration

• Endpoint: POST /api/users/register
• Description: Register a new user.
• Request Body:
  • username (string): User's username (minimum length: 3 characters).
  • email (string): User's email address.
  • password (string): User's password (minimum length: 8 characters).
• Response:
  • 201 Created: User successfully registered.
  • 400 Bad Request: Invalid request or missing data.
  • 422 Unprocessable Entity: Invalid data.

User Login

• Endpoint: POST /api/users/login
• Description: Authenticate user and generate a JWT for further access.
• Request Body:
  • username (string): User's username.
  • password (string): User's password (minimum length: 8 characters).
• Response:
  • 200 OK: Successful login. Returns user information and JWT.
  • 401 Unauthorized: Invalid username or password.
  • 404 Not Found: User not found.
  • 400 Bad Request: Invalid request or missing data.
  • 422 Unprocessable Entity: Invalid data.

Get All Users

• Endpoint: GET /api/users
• Description: Retrieve a paginated list of all users.
• Query Parameters:
  • page (optional, default: 1): Page number.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful retrieval. Returns user information and pagination details.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 500 Internal Server Error: Server error.

Create User

• Endpoint: POST /api/users
• Description: Create a new user.
• Request Body: User data.
• Authentication: Required (JWT).
• Response:
  • 201 Created: User successfully created.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 500 Internal Server Error: Server error.

Get User by ID

• Endpoint: GET /api/users/:id
• Description: Retrieve user details by user ID.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful retrieval. Returns user information.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 404 Not Found: User not found.
  • 500 Internal Server Error: Server error.

Update User by ID

• Endpoint: PUT /api/users/:id
• Description: Update user details by user ID.
• Request Body: Updated user data.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful update. Returns updated user information.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 404 Not Found: User not found.
  • 500 Internal Server Error: Server error.

Delete User by ID

• Endpoint: DELETE /api/users/:id
• Description: Delete a user by user ID.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful deletion. Returns deleted user information.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 404 Not Found: User not found.
  • 500 Internal Server Error: Server error.

Get Users by Domain

• Endpoint: GET /api/users/domain/:domain
• Description: Retrieve users by domain with pagination.
• Query Parameters:
  • page (optional, default: 1): Page number.
  • pageSize (optional, default: 20): Number of users per page.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful retrieval. Returns user information and pagination details.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 500 Internal Server Error: Server error.

Get Users by Availability

• Endpoint: GET /api/users/available/:available
• Description: Retrieve users by availability with pagination.
• Query Parameters:
  • page (optional, default: 1): Page number.
  • pageSize (optional, default: 20): Number of users per page.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful retrieval. Returns user information and pagination details.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 500 Internal Server Error: Server error.

Get Users by Gender

• Endpoint: GET /api/users/gender/:gender
• Description: Retrieve users by gender with pagination.
• Query Parameters:
  • page (optional, default: 1): Page number.
  • pageSize (optional, default: 20): Number of users per page.
• Authentication: Required (JWT).
• **Response

:**

• 200 OK: Successful retrieval. Returns user information and pagination details.
• 401 Unauthorized: Token not provided.
• 403 Forbidden: Invalid token.
• 500 Internal Server Error: Server error.

Search Users by String

• Endpoint: GET /api/users/search/:string
• Description: Search users by string with pagination.
• Query Parameters:
  • page (optional, default: 1): Page number.
• Authentication: Required (JWT).
• Response:
  • 200 OK: Successful retrieval. Returns user information and pagination details.
  • 401 Unauthorized: Token not provided.
  • 403 Forbidden: Invalid token.
  • 500 Internal Server Error: Server error.

Error Handling

In case of errors, the API returns an appropriate HTTP status code along with a JSON response containing details about the error.

Example Error Response:

{
  "error": "Unauthorized: Token not provided"
}

Pagination

The API supports pagination for retrieving lists of users. The response includes information about the total number of users, the current page, and links for navigation to the next and previous pages.

Example Pagination Information:

{
  "numberOfUsers": 10,
  "totalPages": 2,
  "currentPage": 1,
  "users": [...],
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2",
    "prev": null
  }
}

Query Parameters

Various query parameters are supported for specific endpoints to filter and customize the results. Refer to individual endpoint descriptions for details on supported query parameters.

Conclusion

This API provides a simple and flexible way to manage mock user data. Developers can integrate these endpoints into their applications to perform CRUD operations on user records, with support for authentication, pagination, and querying based on different parameters.