API: Addresses
Relevant source files
The following files were used as context for generating this wiki page:
The Addresses API provides a set of endpoints for managing user shipping addresses. This functionality is a core part of the user profile and is essential for the checkout process in the e-commerce system. The business logic for address management resides within the user-app microservice, while the API Gateway exposes the functionality to clients via a RESTful interface.
All address-related operations are authenticated, meaning a valid JWT must be provided for a user to manage their own addresses. The system automatically extracts the userId from the token to ensure users can only access their own data.
Sources: apps/gateway/REFACTORING-GUIDE.md, apps/user-app/test/address.e2e-spec.ts:10-16, postman-collection.json
Architecture and Data Flow
The Addresses feature follows the project's standard microservice architecture. A client request is first received by the API Gateway, which authenticates the user and then forwards the request to the user-app microservice via a NATS message. The user-app contains the service and database logic to handle the request and sends a response back through the same channel.
Sources: SETUP.md, deploys/README.md, apps/gateway/REFACTORING-GUIDE.md
Request-Response Sequence
The diagram below illustrates the sequence of operations for creating a new address.
This diagram shows the flow for creating a user address, from the client request to the database interaction within the user-app.
Sources: apps/user-app/test/address.e2e-spec.ts:80-96, postman-collection.json
API Endpoints
All endpoints are prefixed with /addresses and require authentication. The userId is automatically inferred from the JWT token on the backend.
| Method | Endpoint | Description | Required Role |
|---|---|---|---|
GET | / | List all addresses for the current user. | CUSTOMER |
POST | / | Create a new address for the current user. | CUSTOMER |
PUT | /:addressId | Update an existing address. | CUSTOMER |
DELETE | /:addressId | Delete an existing address. | CUSTOMER |
PUT | /:addressId/set-default | Set a specific address as the default. | CUSTOMER |
Sources: postman-collection.json, apps/user-app/test/address.e2e-spec.ts
Data Models
AddressCreateDto
This DTO is used when creating a new address via the POST /addresses endpoint.
| Field | Type | Description |
|---|---|---|
fullName | string | The full name of the recipient. |
phone | string | The contact phone number. |
street | string | The street name and number. |
ward | string | The ward or sub-district. |
district | string | The district or city area. |
city | string | The city or province. |
isDefault | boolean | Whether this is the default address. |
Sources: postman-collection.json, apps/user-app/test/address.e2e-spec.ts:81-90
AddressUpdateDto
This DTO is used for updating an address via PUT /addresses/:addressId. All fields are optional.
| Field | Type | Description |
|---|---|---|
fullName | string | The full name of the recipient. |
phone | string | The contact phone number. |
street | string | The street name and number. |
ward | string | The ward or sub-district. |
district | string | The district or city area. |
city | string | The city or province. |
isDefault | boolean | Whether this is the default address. |
Sources: postman-collection.json, apps/user-app/test/address.e2e-spec.ts:168-172
Core Business Logic
The address management system contains specific business rules to ensure data integrity and a smooth user experience.
Sources: apps/user-app/test/address.e2e-spec.ts
Automatic Default Address
- On Creation: The very first address created for a user is automatically set as the default address, regardless of the
isDefaultvalue provided in the request payload. This ensures a user always has a default address after creating their first one. - On Deletion: If a user deletes their current default address while having other addresses available, the system automatically promotes one of the remaining addresses to be the new default.
The following flowchart illustrates the logic when deleting a default address.
This diagram shows how the system handles the deletion of an address, including the automatic reassignment of the default status.
Sources: apps/user-app/test/address.e2e-spec.ts:285-322
Setting a Default Address
When a user sets an address as their new default via PUT /addresses/:id/set-default, the system performs two key operations in a transaction:
- It finds the user's current default address and sets its
isDefaultflag tofalse. - It sets the
isDefaultflag of the target address totrue.
This ensures that a user can only have one default address at any given time.
Sources: apps/user-app/test/address.e2e-spec.ts:193-231
Testing
The functionality of the Addresses API is validated through a comprehensive End-to-End (E2E) test suite located in apps/user-app/test/address.e2e-spec.ts. These tests cover the full lifecycle of address management by sending messages directly to the NATS-based microservice.
Key test scenarios include:
- Creating the first address and verifying it becomes the default.
- Listing all addresses for a specific user.
- Updating an existing address.
- Setting a new default address and ensuring the old one is unset.
- Deleting a non-default address.
- Deleting a default address and verifying a new one is automatically assigned.
- Handling errors for non-existent users or addresses.