Shopping list

Application Overview

This application supports user, group, shopping list, and notification management, allowing users to collaborate on shared shopping lists with automated notifications for updates.

Key Features

User Management

• Create Account: Users can register by providing a username, email, phone number, and password.
• Login: Authenticate using email and password.
• Update Password: Users can change their password post-login.

User Group Management

• Update Group: Allows updating of group name and description.
• Restrictions:
  • Groups are automatically created when a new shopping list is created and are removed when the shopping list is deleted.
  • There are no direct methods for creating or deleting groups.

Group Membership Management

• Add/Remove Member: Add or remove members from a group.
• Automatic Notifications: Notifications are automatically generated when members are added or removed.
• Restrictions: PATCH operations are not supported for Group Membership.

Shopping List Management

• Create Shopping List: Creating a shopping list also creates a corresponding group with the list creator as the initial member.
• Update Shopping List: Users can update the shopping list's name and description, which generates a notification.
• Delete Shopping List: Deleting a shopping list removes all related notifications, products, group members, and the group itself.
• Add Members: Additional members can be added to the group via the GroupMembership table.

Shopping List Product Management

• Product Operations: Products can be added, modified, or deleted within a shopping list.
• Automatic Notifications: Adding, modifying, or deleting a product triggers an automatic notification.

Notification Management

• View Notifications: Notifications are read-only; they cannot be created, updated, or deleted manually.

---

Getting Started

To get started with the project, follow the steps below:

1. Clone the Repository

Open your terminal and run the following command:

git clone https://github.com/SubriaIs/shopping_list.git

2. Run the Application Using Docker Compose

Ensure you have Docker and Docker Compose installed on your machine. Then, execute the following command to start the application:

docker-compose up -d

User APIs Documentation

Overview

The User API provides a comprehensive set of endpoints for managing users, including user login, retrieval, creation, updating, and deletion.

Token Requirements

Token Overview

• Certain endpoints in the User API require a valid token for authentication.
• The token must be included in the request header as xToken.

Token Generation

• Users can obtain a token by successfully logging in with their email and password.

Token Usage

• Include the token in the header for all requests to endpoints marked as requiring a token.

API Endpoints

🔄 HTTP Method	🛣️ Endpoint	📝 Description	📥 Request Body	📤 Response	❗ Error Handling	🛠️ cURL Command	🔑 Token Required
GET	/v1/user	Fetches all users from the database.	None	List of User objects in JSON format.	Returns 404 Not Found if no users are found. Throws SLServiceException with details.	curl --location 'http://localhost:8082/v1/user' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/user/id/{id}	Fetches a single user by their id.	None	User object in JSON format.	Returns 404 Not Found if the user with the given id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/user/id/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/user/name/{name}	Fetches a single user by their name.	None	User object in JSON format.	Returns 404 Not Found if the user with the given name is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/user/name/{name}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/user/logged	Fetches the currently logged-in user based on the provided token.	None	User object in JSON format	Returns 404 Not Found if no user is found for the token. Throws SLServiceException with details.	curl --location 'http://localhost:8082/v1/user/logged' --header 'xToken: <your-token>'	✅ Yes
POST	/v1/user/login	Logs in a user using email and password and returns a token.	{"email": "...", "password": "..."}	TokenResponse with token in JSON format.	Returns 404 Not Found if the email and password do not match any user. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/user/login' --header 'Content-Type: application/json' --data-raw '{"email":"test@gmail.com","password":"password"}'	❌ No
POST	/v1/user	Adds a new user to the system.	User JSON	Status 201 Created on successful creation.	Returns 400 Bad Request if a user with the same email already exists. Throws SLServiceException for duplicates.	curl --location 'http://localhost:8082/v1/user' --header 'Content-Type: application/json' --data-raw '{"userName": "rijk Islam", "email": "rijk@jefsk.com", "phoneNumber": "+48334956678", "password": "1237980494"}'	❌ No
PATCH	/v1/user/id/{id}	Updates an existing user by their id.	User JSON	Updated User object in JSON format.	Returns 404 Not Found if the user with the given id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/user/id/{id}' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"password":"newpassword"}'	✅ Yes
DELETE	/v1/user/id/{id}	Deletes an existing user by their id.	None	Status 204 No Content on successful deletion.	Returns 404 Not Found if the user with the given id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/user/id/{id}' --header 'xToken: <your-token>'	✅ Yes

Notes

• Make sure to replace <your-token> with the actual token value for authenticated requests.
• Adjust the id, name, and user details as necessary when making requests.

User Group API Endpoints

🔄 HTTP Method	🛣️ Endpoint	📝 Description	📥 Request Body	📤 Response	❗ Error Handling	🛠️ cURL Command	🔑 Token Required
GET	/v1/group	Fetches all user groups from the database.	None	List of UserGroup objects in JSON format.	Returns 404 Not Found if no groups are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/group/id/{id}	Fetches a single user group by its id.	None	UserGroup object in JSON format.	Returns 404 Not Found if the group with the given id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/id/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/group/createdBy/{id}	Fetches all user groups created by a specific user id.	None	List of UserGroup objects in JSON format.	Returns 404 Not Found if no groups created by the user are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/createdBy/{id}' --header 'xToken: <your-token>'	✅ Yes
PATCH	/v1/group/id/{id}	Updates an existing user group by its id if the requester is creator.	UserGroup JSON	Updated UserGroup object in JSON format.	Returns 404 Not Found if the group with the given id is not found, 401 Unauthorized if token mismatch.	curl --location 'http://localhost:8082/v1/group/id/{id}' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"groupName":"New Group Name","description":"family shopping"}'	✅ Yes

GroupMemberShip API Endpoints

🔄 HTTP Method	🛣️ Endpoint	📝 Description	📥 Request Body	📤 Response	❗ Error Handling	🛠️ cURL Command	🔑 Token Required
GET	/v1/group/member	Fetches all group members from the database.	None	List of GroupMemberShip objects in JSON format.	Returns 404 Not Found if no group members are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/member' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/group/member/id/{id}	Fetches a specific group member by their id.	None	GroupMemberShip object in JSON format.	Returns 404 Not Found if the group member with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/member/id/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/group/member/groupId/{id}	Fetches all members of a specific group by groupId.	None	List of GroupMemberShip objects in JSON format.	Returns 404 Not Found if no members are found for the specified group. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/member/groupId/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/group/member/userId/{id}	Fetches all groups a specific user belongs to by userId.	None	List of GroupMemberShip objects in JSON format.	Returns 404 Not Found if no groups are found for the specified user. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/member/userId/{id}' --header 'xToken: <your-token>'	✅ Yes
POST	/v1/group/member	Adds a user to a group as a member.	GroupMemberShip JSON	Status 201 Created	Returns 400 Bad Request if the user is already a member, or if user or group is invalid. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/member' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"userGroup": {"groupId": 1}, "user": {"userId": 2}}'	✅ Yes
DELETE	/v1/group/member/id/{id}	Deletes a specific group member by id.	None	Status 204 No Content	Returns 404 Not Found if the group member with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/group/member/id/{id}' --header 'xToken: <your-token>' --request DELETE	✅ Yes

Shopping List API Endpoints

🔄 HTTP Method	🛣️ Endpoint	📝 Description	📥 Request Body	📤 Response	❗ Error Handling	🛠️ cURL Command	🔑 Token Required
GET	/v1/shoppingList	Fetches all shopping lists from the database.	None	List of ShoppingList objects in JSON format.	Returns 404 Not Found if no shopping lists are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/id/{id}	Fetches a specific shopping list by its id.	None	ShoppingList object in JSON format.	Returns 404 Not Found if the shopping list with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/id/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/group/{id}	Fetches shopping lists by groupId.	None	ShoppingList object in JSON format.	Returns 404 Not Found if the group with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/group/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/user/shared	Fetch all shopping lists those are shared to user.	None	List of ShoppingList objects in JSON format.	Returns 404 Not Found if no shared shopping lists are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/user/shared' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/user/all	Fetch all shopping lists (shared and owned) of user.	None	List of ShoppingList objects in JSON format.	Returns 404 Not Found if no shopping lists are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/user/all' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/user/owned	Fetch all shopping lists those are owned by user.	None	List of ShoppingList objects in JSON format.	Returns 404 Not Found if no owned shopping lists are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/user/owned' --header 'xToken: <your-token>'	✅ Yes
POST	/v1/shoppingList	Creates a new shopping list.	ShoppingList JSON	Status 201 Created	Returns 500 Internal Server Error if an error occurs during creation.	curl --location 'http://localhost:8082/v1/shoppingList' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"shoppingListName":"Groceries", "description":"Description"}'	✅ Yes
PATCH	/v1/shoppingList/id/{id}	Updates an existing shopping list by its id.	ShoppingList JSON	Updated ShoppingList object in JSON format.	Returns 404 Not Found if the shopping list with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/id/{id}' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"shoppingListName":"Update Groceries", "description":"Update Description"}'	✅ Yes
DELETE	/v1/shoppingList/id/{id}	Deletes a specific shopping list by its id.	None	Status 204 No Content	Returns 404 Not Found if the shopping list with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/id/{id}' --header 'xToken: <your-token>' --request DELETE	✅ Yes

Shopping List Product API Endpoints

🔄 HTTP Method	🛣️ Endpoint	📝 Description	📥 Request Body	📤 Response	❗ Error Handling	🛠️ cURL Command	🔑 Token Required
GET	/v1/shoppingList/product	Fetches all shopping list products from the database.	None	List of ShoppingListProduct objects in JSON format.	Returns 404 Not Found if no shopping list products are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/product' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/product/id/{id}	Fetches a specific shopping list product by its id.	None	ShoppingListProduct object in JSON format.	Returns 404 Not Found if the shopping list product with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/product/id/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/shoppingList/product/shoppingListId/{id}	Fetches all shopping list products for a specific shopping list.	None	List of ShoppingListProduct objects in JSON format.	Returns 404 Not Found if no products for the specified shopping list are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/product/shoppingListId/{id}' --header 'xToken: <your-token>'	✅ Yes
POST	/v1/shoppingList/product	Creates a new shopping list product.	ShoppingListProduct JSON	Created ShoppingListProduct object in JSON format.	Returns 500 Internal Server Error if an error occurs during creation.	curl --location 'http://localhost:8082/v1/shoppingList/product' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"shoppingList": { "shoppingListId" : 5 }, "productName":"apple", "quantity": 90, "unit": "Kg", "purchase": false}'	✅ Yes
PATCH	/v1/shoppingList/product/id/{id}	Updates an existing shopping list product by its id.	ShoppingListProduct JSON	Updated ShoppingListProduct object in JSON format.	Returns 404 Not Found if the shopping list product with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/product/id/{id}' --header 'xToken: <your-token>' --header 'Content-Type: application/json' --data-raw '{"productName":"Updated Apples", "quantity": 5, "unit": "Kg", "purchase": true }'	✅ Yes
DELETE	/v1/shoppingList/product/id/{id}	Deletes a specific shopping list product by its id.	None	Status 204 No Content	Returns 404 Not Found if the shopping list product with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/shoppingList/product/id/{id}' --header 'xToken: <your-token>' --request DELETE	✅ Yes

Notification API Endpoints

🔄 HTTP Method	🛣️ Endpoint	📝 Description	📥 Request Body	📤 Response	❗ Error Handling	🛠️ cURL Command	🔑 Token Required
GET	/v1/notification	Fetches all notifications from the database.	None	List of Notification objects in JSON format.	Returns 404 Not Found if no notifications are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/notification' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/notification/id/{id}	Fetches a specific notification by its id.	None	Notification object in JSON format.	Returns 404 Not Found if the notification with the specified id is not found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/notification/id/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/notification/groupId/{id}	Fetches all notifications for a specific group by id.	None	List of Notification objects in JSON format.	Returns 404 Not Found if no notifications for the specified group are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/notification/groupId/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/notification/triggeredBy/{id}	Fetches all notifications triggered by a specific user by id.	None	List of Notification objects in JSON format.	Returns 404 Not Found if no notifications triggered by the specified user are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/notification/triggeredBy/{id}' --header 'xToken: <your-token>'	✅ Yes
GET	/v1/notification/user/{id}	Fetches all notifications for a specific user by id.	None	List of Notification objects in JSON format.	Returns 404 Not Found if no notifications for the specified user are found. Throws SLServiceException.	curl --location 'http://localhost:8082/v1/notification/user/{id}' --header 'xToken: <your-token>'	✅ Yes

Error Handling

All endpoints return appropriate HTTP status codes and error messages:

• 400 Bad Request: For invalid input, duplicate data (e.g., when trying to add a user with an existing email).
• 401 Unauthorized: When an invalid or missing xToken is provided for protected endpoints.
• 404 Not Found: When a user or resource is not found (e.g., when fetching by id or name).
• SLServiceException: Custom exception thrown with error details such as error message, status code, and additional information.