Skip to main content

​
Base URL

The User Management API is accessible at: 
http://localhost:8080/api/v1
For production environments, replace localhost:8080 with your deployed API domain.

​
Getting Started

The User Management API provides RESTful endpoints for managing user records in your application. All endpoints accept and return JSON data.

​
Quick Start

  1. Register a new user using POST /api/v1/users
  2. Retrieve users using GET /api/v1/users or GET /api/v1/users/{id}
  3. Update user details using PUT /api/v1/users/{id}
  4. Delete a user using DELETE /api/v1/users/{id}

​
Available 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
DELETE/api/v1/users/{id}Delete user

​
Authentication

Currently, this API does not require authentication. If you’re deploying to production, consider implementing Spring Security for endpoint protection.

​
Content Type

All requests that send data must include the Content-Type: application/json header. All responses return Content-Type: application/json.

​
Common Error Responses

The API uses RFC 7807 Problem Details format for error responses.

​
400 Bad Request

Returned when request validation fails (missing required fields, invalid format, etc.). 
{
  "type": "about:blank",
  "title": "Validation Failed",
  "status": 400,
  "detail": "username: username is required; email: email must be a valid email address",
  "timestamp": "2024-01-15T10:30:00"
}

​
404 Not Found

Returned when a requested user doesn’t exist. 
{
  "type": "about:blank",
  "title": "User Not Found",
  "status": 404,
  "detail": "User not found with id: 0f4df2de-fffb-4a24-9891-381ecf4f0f87",
  "userId": "0f4df2de-fffb-4a24-9891-381ecf4f0f87",
  "timestamp": "2024-01-15T10:30:00"
}

​
409 Conflict

Returned when attempting to create a user that already exists. 
{
  "type": "about:blank",
  "title": "User Already Exists",
  "status": 409,
  "detail": "User with username 'jdoe' already exists",
  "timestamp": "2024-01-15T10:30:00"
}

​
500 Internal Server Error

Returned when an unexpected error occurs. 
{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "timestamp": "2024-01-15T10:30:00"
}

​
User Roles

The API supports three user roles:
  • ADMIN - Administrative access
  • USER - Standard user access
  • GUEST - Guest access

​
Interactive Documentation

For interactive API testing, visit the Swagger UI at: 
http://localhost:8080/swagger-ui/index.html
OpenAPI specification is available at: 
http://localhost:8080/api-docs

Build docs developers (and LLMs) love

Get started for freeTalk to us