Skip to main content

​
Welcome to User Management API

User Management API is a production-ready, extensible RESTful service built with Spring Boot. It provides endpoints for creating, reading, updating, and deleting user records, following a clean hexagonal (ports and adapters) architecture for maintainability, testability, and flexibility.

Quickstart

Get up and running in minutes with our quick start guide

API Reference

Explore the complete API documentation

Architecture

Learn about the hexagonal architecture and design patterns

Docker Guide

Deploy with Docker and Docker Compose

​
Key Features

Complete CRUD Operations

Full suite of Create, Read, Update, and Delete operations for user management

Hexagonal Architecture

Clean separation of concerns with ports and adapters pattern

CQRS Pattern

Optimized data access with Command Query Responsibility Segregation

OpenAPI/Swagger

Interactive API documentation with Swagger UI

PostgreSQL Persistence

Robust data persistence with JPA and PostgreSQL

Exception Handling

Centralized exception handling with RFC 7807 Problem Details

Domain-Driven Design

Rich business logic with DDD principles

CI/CD Ready

Docker support with Google Cloud Build integration

​
API Endpoints

The API provides five core endpoints for user management:
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
All endpoints accept and return JSON. The API runs on http://localhost:8080 by default.

​
Design Principles

This project demonstrates modern software engineering practices:
  • Hexagonal Architecture - Framework-agnostic core with replaceable adapters
  • CQRS - Separated read and write operations for optimal performance
  • Domain-Driven Design - Business logic expressed through domain models
  • Dependency Inversion - High-level modules depend on abstractions, not implementations
  • Repository Pattern - Clean data access layer with testable interfaces
  • Use Case Pattern - Explicit application capabilities as interfaces
The architecture allows you to swap infrastructure components (like the database or REST layer) without touching the core business logic.

​
Quick Example

Here’s a quick example of creating a new user:
cURL
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"
  }'
Response: 
{
  "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
}

​
Next Steps

Get Started

Follow the quickstart guide to run the API locally

Explore Architecture

Understand the architectural patterns and principles

Build docs developers (and LLMs) love

Get started for freeTalk to us