User APIs Documentation
The UserController handles user-related actions, such as
retrieving user information, managing friendships, and updating user
data. See the User Guide for more info.
Controller Route: /api/users
All routes within the UserController are prefixed by
/api/users.
Summary of Endpoints
| Endpoint | Method | Description | Authorization |
|---|---|---|---|
/api/users/get |
GET | Fetches user details by user ID. | Admin, User, Pass |
/api/users/search |
GET | Searches users by username. | Admin, User, Pass |
/api/users/add-friend |
POST | Adds a user as a friend. | Admin, User, Pass |
/api/users/remove-friend |
POST | Removes a user from friends. | Admin, User, Pass |
/api/users/current |
GET | Retrieves the current logged-in user's details. | Admin, User, Pass |
/api/users/create |
POST | Creates a new user with specified role. | Admin, Server |
/api/users/delete |
POST | Deletes a user by ID. | Admin |
/api/users/update |
PATCH | Updates a user's profile information. | Admin, User, Pass |
/api/users/change-username |
PATCH | Changes the username for a user. | Admin, User, Pass |
/api/users/change-password |
PATCH | Changes the password for a user. | Admin, User, Pass |
Get User by ID
Fetches the details of a user by their user ID.
Details:
- Endpoint:
/api/users/get - Method:
GET - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- id (string, required): The ID of the user.
Responses:
- 200 OK: Returns the user details.
- 404 Not Found: If the user is not found.
- 401 Unauthorized: If access is restricted based on user privacy settings.
Example Request:
curl -X GET "https://your-api-url.com/api/users/get?id=66bc99b8ab7ba419497e21af" \
-H "Authorization: Bearer <JWT-token>"
Search Users
Searches for users by their username.
Details:
- Endpoint:
/api/users/search - Method:
GET - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- username (string, optional): The username to search for (supports partial matches).
Responses:
- 200 OK: Returns a list of matching users.
- 404 Not Found: If no users match the search criteria.
Example Request:
curl -X GET "https://your-api-url.com/api/users/search?username=Epsi" \
-H "Authorization: Bearer <JWT-token>"
Add Friend
Adds a user to the current user's friend list.
Details:
- Endpoint:
/api/users/add-friend - Method:
POST - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- id (string, required): The ID of the user to add as a friend.
Responses:
- 200 OK: Returns success if the user is added as a friend.
- 404 Not Found: If the user is not found.
- 401 Unauthorized: If the action is not authorized.
Example Request:
curl -X POST "https://your-api-url.com/api/users/add-friend?id=66bc99b8ab7ba419497e21af" \
-H "Authorization: Bearer <JWT-token>"
Remove Friend
Removes a user from the current user's friend list.
Details:
-
Endpoint:
/api/users/remove-friend - Method:
POST - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- id (string, required): The ID of the user to remove as a friend.
Responses:
- 200 OK: Returns success if the user is removed from friends.
- 404 Not Found: If the user is not found.
- 401 Unauthorized: If the action is not authorized.
Example Request:
curl -X POST "https://your-api-url.com/api/users/remove-friend?id=user123" \
-H "Authorization: Bearer <JWT-token>"
Get Current User
Retrieves the details of the currently logged-in user.
Details:
- Endpoint:
/api/users/current - Method:
GET - Authorization: JWT (Roles: Admin, User, Pass)
Responses:
- 200 OK: Returns the current user's details.
- 404 Not Found: If the user is not found.
Example Request:
curl -X GET "https://your-api-url.com/api/users/current" \
-H "Authorization: Bearer <JWT-token>"
Create User
Creates a new user with a username, password, and role.
Details:
- Endpoint:
/api/users/create - Method:
POST - Authorization: JWT (Roles: Admin, Server)
Parameters:
- username (string, required): The username for the new user.
- password (string, required): The password for the new user.
-
role (string, optional): The role for the new user
(defaults to
User).
Responses:
- 200 OK: Returns the user ID of the created user.
- 400 Bad Request: If the password is empty.
Example Request:
curl -X POST "https://your-api-url.com/api/users/create?username=newuser&password=Password123&role=User" \
-H "Authorization: Bearer <JWT-token>"
Delete User
Deletes a user by their user ID.
Details:
- Endpoint:
/api/users/delete - Method:
POST - Authorization: JWT (Roles: Admin)
Parameters:
- id (string, required): The ID of the user to delete.
Responses:
- 200 OK: Returns success if the user is deleted.
- 404 Not Found: If the user is not found.
- 401 Unauthorized: If the action is not authorized.
Example Request:
curl -X POST "https://your-api-url.com/api/users/delete?id=user123" \
-H "Authorization: Bearer <JWT-token>"
Update User
Updates the profile information of a user.
Details:
- Endpoint:
/api/users/update - Method:
PATCH - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- id (string, required): The ID of the user.
- bio (string, optional): The bio for the user.
- role (string, optional): The role for the user (Admin only).
- publicStats (string, optional): Whether the user's stats are public.
- favTrackId (string, optional): The ID of the user's favorite track.
- favAlbumId (string, optional): The ID of the user's favorite album.
- favArtistId (string, optional): The ID of the user's favorite artist.
Responses:
- 200 OK: Returns success if the user profile is updated.
- 404 Not Found: If the user is not found.
- 401 Unauthorized: If the action is not authorized.
Example Request:
curl -X PATCH "https://your-api-url.com/api/users/update?id=user123&bio=New bio" \
-H "Authorization: Bearer <JWT-token>"
Change Username
Changes the username of a user.
Details:
-
Endpoint:
/api/users/change-username - Method:
PATCH - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- id (string, required): The ID of the user.
- username (string, required): The new username for the user.
Responses:
- 200 OK: Returns success if the username is updated.
- 404 Not Found: If the user is not found.
- 401 Unauthorized: If the action is not authorized.
Example Request:
curl -X PATCH "https://your-api-url.com/api/users/change-username?id=user123&username=newusername" \
-H "Authorization: Bearer <JWT-token>"
Change Password
Changes the password of a user.
Details:
-
Endpoint:
/api/users/change-password - Method:
PATCH - Authorization: JWT (Roles: Admin, User, Pass)
Parameters:
- id (string, required): The ID of the user.
- password (string, required): The new password for the user.
Responses:
- 200 OK: Returns success if the password is updated.
- 404 Not Found: If the user is not found.
- 401 Unauthorized
: If the action is not authorized.
Example Request:
curl -X PATCH "https://your-api-url.com/api/users/change-password?id=user123&password=newpassword" \
-H "Authorization: Bearer <JWT-token>"