Website is hosted at = https://heliverse-phi.vercel.app/
Server is hosted at = https://heliverse-server-v1.onrender.com/
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.
The base URL for the API is http://localhost:{PORT}
, where {PORT}
is the port number specified during the server setup.
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.
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
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"
}
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
}
}
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.
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.