Skip to main content
This guide will walk you through getting the User Management API running on your local machine, from installation to making your first API call.
1

Prerequisites

Before you begin, ensure you have the following installed:
  • Java 21 - Required for Spring Boot 3.5.10
  • PostgreSQL (optional) - The API uses an in-memory H2 database by default for quick setup
  • Git - To clone the repository
You don’t need to install Gradle separately. The project includes the Gradle wrapper (./gradlew).
Verify your Java version:
java -version
You should see Java 21 in the output.
2

Clone the Repository

Clone the User Management API repository and navigate to the project directory:
git clone https://gitlab.com/ferney.estupinan/user-management-api.git
cd user-management-api
3

Build the Project

Build the project using the Gradle wrapper. This will download all dependencies and compile the application:
./gradlew build
The first build may take a few minutes as Gradle downloads all dependencies. Subsequent builds will be much faster.
The build process includes:
  • Compiling Java source code
  • Running unit and integration tests
  • Creating the executable JAR file
4

Run the Application

Start the application using Gradle:
./gradlew bootRun
You should see output similar to:
Started Application in 3.456 seconds (process running for 3.789)
The API is now running at http://localhost:8080
By default, the application runs with the local profile, which uses an in-memory H2 database. This is perfect for testing without setting up PostgreSQL.
5

Make Your First API Call

Let’s register your first user! Open a new terminal window and run:
curl -X POST http://localhost:8080/api/v1/users \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "jdoe",
    "email": "jdoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "USER"
  }'
Success Response (201 Created):
{
  "id": "0f4df2de-fffb-4a24-9891-381ecf4f0f87",
  "username": "jdoe",
  "email": "jdoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "USER",
  "createdAt": "2024-01-15T10:30:00",
  "updatedAt": "2024-01-15T10:30:00",
  "active": true
}
The id field is a UUID that’s automatically generated by the system.
Now retrieve the user you just created:
curl http://localhost:8080/api/v1/users
You’ll get a list of all users:
[
  {
    "id": "0f4df2de-fffb-4a24-9891-381ecf4f0f87",
    "username": "jdoe",
    "email": "jdoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "USER",
    "createdAt": "2024-01-15T10:30:00",
    "updatedAt": "2024-01-15T10:30:00",
    "active": true
  }
]
6

Explore the Swagger UI

The API includes interactive documentation powered by Swagger/OpenAPI. Open your browser and navigate to:http://localhost:8080/swagger-ui/index.htmlThe Swagger UI allows you to:
  • View all available endpoints
  • See request/response schemas
  • Test API calls directly from your browser
  • Download the OpenAPI specification

Try It Out

Use the “Try it out” button on any endpoint to make test requests without writing curl commands.

​
Available Endpoints

The API provides the following user management endpoints:
MethodEndpointDescription
POST/api/v1/usersRegister a new user
GET/api/v1/usersGet all users
GET/api/v1/users/{id}Get user by ID
PUT/api/v1/users/{id}Update user by ID
DELETE/api/v1/users/{id}Delete user by ID

​
Configuration Options

​
Using PostgreSQL Instead of H2

If you want to use PostgreSQL for persistent storage, you can configure the database connection using environment variables: 
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/user_db
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=password
export ENVIRONMENT=local

./gradlew bootRun
For the complete setup with PostgreSQL, create a docker-compose.yml file: 
version: '3.8'
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: user_db
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
  api:
    build: .
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/user_db
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: password
      ENVIRONMENT: local
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
Then run: 
docker compose up --build

​
Next Steps

Architecture Guide

Learn about hexagonal architecture, CQRS, and DDD patterns

API Reference

Explore all available API endpoints in detail

Configuration

Deep dive into configuration options and environment variables

Testing

Learn how to run tests and view coverage reports

​
Troubleshooting

If port 8080 is already in use, you can change it by setting the SERVER_PORT environment variable:
export SERVER_PORT=8081
./gradlew bootRun
This project requires Java 21. If you have multiple Java versions installed, set JAVA_HOME:
export JAVA_HOME=/path/to/java21
./gradlew bootRun
If you’re using PostgreSQL and seeing connection errors:
  1. Verify PostgreSQL is running: pg_isready
  2. Check credentials in environment variables
  3. Ensure the database exists: createdb user_db
  4. Check firewall rules for port 5432
Clear the Gradle cache and rebuild:
./gradlew clean build --refresh-dependencies

​
Health Check

To verify the API is running correctly, check the health endpoint: 
curl http://localhost:8080/actuator/health
Expected response: 
{
  "status": "UP"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us