This project provides a simple and clear REST API for managing users.
The design follows the principle "Keep it simple, but not simpler", focusing on readability, maintainability, and practical scalability.
The codebase is structured to be:
- Easy to read
- Easy to debug
- Easy to maintain
- Easy to extend when the application grows
The goal is not to over-engineer the solution, but to provide a clean and functional implementation that demonstrates good API design practices.
This project implements a REST API for user management using Spring Boot. The API supports CRUD operations and dynamic querying features such as filtering and sorting. The system uses in-memory storage, so no database configuration is required to run the project. Main features include: creating users, retrieving users, dynamic filtering, dynamic sorting, partial updates using PATCH, deleting users, field validation (email, phone, RFC), password encryption, global exception handling, and Swagger automatic API documentation.
Java 21+, Spring Boot, Jakarta Validation, Lombok, Swagger/OpenAPI, Maven.
controller – HTTP request handling
service – business logic
model – data structures
utils – utility helpers
validations – custom validations
handler – global exception handling
Start the application using Maven:
mvn spring-boot:run
Alternatively build and run the jar:
mvn clean install
java -jar target/*.jar
The application will run by default at:
http://localhost:8095
The API is self-documented using Swagger/OpenAPI. You can access the interactive documentation here:
http://localhost:8095/swagger-ui.html
or
http://localhost:8095/swagger-ui/index.html
Swagger allows you to explore endpoints, inspect request and response schemas, and test the API directly from the browser.
/api/v1/users
Available endpoints:
GET /users – retrieve users
POST /users – create user
PATCH /users/{id} – partial update
DELETE /users/{id} – delete user
Endpoint: POST /api/v1/users
Example request body:
{
"name": "Carlos Gomez",
"email": "carlos@test.com",
"password": "Password123!",
"phone": "5512345678",
"tax_id": "GOMC850412AB3"
}
Notes: the id is automatically generated by the server, created_at is generated automatically, and the password is encrypted before storage.
Retrieve all users:
GET /api/v1/users
The API supports dynamic filtering using the following syntax:
filter=field+operator+value
Example:
GET /api/v1/users?filter=name+co+user
Supported operators:
eq – equals
co – contains
sw – starts with
ew – ends with
dif – different
Examples:
/users?filter=name+eq+user1
/users?filter=email+co+mail
/users?filter=name+sw+car
/users?filter=email+ew+mail.com
Sorting can be applied using:
sortedBy=field
Example:
GET /users?sortedBy=name
Descending order:
GET /users?sortedBy=-email
PATCH updates only the fields provided in the request body.
Endpoint: PATCH /api/v1/users/{id}
Example request body: { "phone": "5599999999" }
Only the provided fields are modified.
Endpoint: DELETE /api/v1/users/{id}
Response status: 204 No Content
Email must be valid and unique.
Phone must contain exactly 10 digits, for example: 5512345678.
RFC (tax_id) must follow the format: 3–4 letters + 6 digit date + 3 SAT characters. Example: GOMC850412AB3. RFC length must be between 12 and 13 characters.
Create user: POST /users
Retrieve users: GET /users
Filter users: GET /users?filter=name+co+user
Sort users: GET /users?sortedBy=name
Update user: PATCH /users/{id}
Delete user: DELETE /users/{id}
Duplicate email is rejected to prevent multiple users with the same email.
Invalid RFC format is rejected.
Invalid phone format is rejected if it does not contain exactly 10 digits.
Invalid filter syntax such as filter=name+eq is rejected.
Updating or deleting a non-existing user returns an error.
Empty filter parameters are safely ignored.
Empty PATCH requests are allowed but do not modify data.
Errors are handled using a GlobalExceptionHandler. Example error response: { "status": 400, "method": "POST", "path": "/api/v1/users", "message": "phone must contain exactly 10 digits", "timestamp": "2026-03-15T15:25:00" }
You can test the API using Postman by creating a collection with the following requests:
POST /api/v1/users – create user
GET /api/v1/users – list users
GET /api/v1/users?filter=name+co+user – filter users
GET /api/v1/users?sortedBy=name – sort users
PATCH /api/v1/users/{id} – update user
DELETE /api/v1/users/{id} – delete user
To import into Postman: open Postman, create a new collection, add the endpoints listed above, configure the base URL as http://localhost:8095/api/v1/users, and run the requests sequentially.
This implementation focuses on clean code, separation of concerns, validation, REST standards, and predictable error responses. Since the storage is in memory, all data will be reset when the application restarts.
Future improvements may include adding database persistence, pagination, multi-filter queries, authentication and authorization, DTO layer separation, automated unit testing, and rate limiting.