💬 Chat Application REST API

Version: 2.8.13
Specification: OpenAPI 3.1
License: Apache 2.0
Server: http://localhost:1376

---

📖 Overview

The Chat Application REST API is a modular and secure backend designed for real-time chat systems.
It supports role-based access control, audit logging, session management, WebSocket communication, and file attachments.

This API provides all endpoints required to manage users, roles, permissions, rooms, messages, and notifications — built with Spring Boot, Spring Security (JWT), and JPA.

The Chat Application REST API is a modern, modular, and secure backend system built using Spring Boot and Spring Security (JWT). It provides a comprehensive set of endpoints to manage real-time chat functionality, including users, roles, permissions, chat rooms, messages, attachments, notifications, and audit logging.

The architecture is designed to be scalable, maintainable, and testable, following clean coding principles and domain separation. All operations are exposed via RESTful APIs, and fully documented using Swagger (OAS 3.1) for easy client integration.

---

⚙️ Key Features

• Authentication & Authorization

  • Secure login using JWT-based authentication.
  • Role-based access control (RBAC) with fine-grained permission management.
  • Support for @PreAuthorize annotations for method-level security.

• User Management

  • Full CRUD operations for users.
  • Role assignment/unassignment with real-time validation.
  • Password reset and session tracking.

• Role & Permission System

  • Dynamic permission assignment for flexible access control.
  • Super Admin privileges for critical operations.

• Chat Management

  • Public and private room creation and participation.
  • Real-time messaging endpoints with history tracking.
  • Message search, recent message retrieval, and media attachments.

• Notifications

  • User-specific and global notifications.
  • Mark-as-read and unread count endpoints.

• Audit Logging

  • Comprehensive tracking of create, update, and delete operations.
  • Exportable reports in PDF and Excel formats.

• Attachments

  • Upload and download APIs for message-related files.
  • File-type filtering and deletion management.

---

🧩 Architecture

The application follows a layered architecture:

• Controller Layer → Handles REST API requests and responses.
• Service Layer → Contains business logic and validation.
• Repository Layer → Interacts with the database using Spring Data JPA.
• Security Layer → Manages authentication, JWT tokens, and role checks.
• Audit Layer → Tracks all CRUD activities for traceability.

It also supports WebSocket integration for real-time communication (via a separate module or extension).

---

🔐 Security

• JWT-based Authentication ensures stateless session management.

• Spring Security intercepts and validates all incoming requests.

• Each endpoint is protected via annotations like:

  @PreAuthorize("hasRole('SUPER_ADMIN')")

• The app supports Basic Auth for Swagger testing using:

  Available authorizations:
  basicScheme (http, Basic)
  

  which allows developers to test secured endpoints easily from Swagger UI.

---

🧠 Technologies Used

Category	Technology
Language	Java 17+
Framework	Spring Boot 3.x
Security	Spring Security, JWT
Database	PostgreSQL
Documentation	Swagger / OpenAPI 3.1
Build Tool	Maven / Gradle
Logging	SLF4J, Logback
File Export	Apache POI (Excel), iText / PDFBox (PDF)
Version Control	Git / GitHub
Containerization	Docker (optional)

---

🧪 Testing

• Endpoints can be tested using:

  • Swagger UI: /swagger-ui/index.html
  • Postman collections (exported from Swagger)
  • Integration tests written with Spring Boot Test framework

---

🔐 Authorization

This API uses JWT-based authentication and role-based access control.

You can authorize via Swagger UI:

1. Click on Authorize button.

2. Enter your JWT Token in the following format:

3. Roles such as SUPER_ADMIN, ADMIN, or USER determine your access level.

---

🚀 Modules and Endpoints

🧑‍💼 Chat Users (SUPER_ADMIN Only)

Manage chat users and their roles.

Method	Endpoint	Description
GET	/api/super_admin/users	Get all users
POST	/api/super_admin/users	Create a new user
PUT	/api/super_admin/users/{id}	Update a user
DELETE	/api/super_admin/users/{id}	Delete a user
POST	/api/super_admin/users/{id}/assign-roles	Assign roles to a user
POST	/api/super_admin/users/{id}/unassign-roles	Unassign roles from a user

---

🛡 Permissions

Manage system permissions (used by roles).

Method	Endpoint	Description
GET	/api/permissions	Get all permissions
POST	/api/permissions	Create a new permission
PUT	/api/permissions/{id}	Update permission
DELETE	/api/permissions/{id}	Delete permission

---

🧾 Audit Logs

Track system activities and changes.

Method	Endpoint	Description
GET	/api/audit	Get all audit logs
GET	/api/audit/{entityType}/{entityId}	Get logs by entity type and ID
GET	/api/audit/export/pdf	Export logs to PDF
GET	/api/audit/export/excel	Export logs to Excel

---

🧩 Roles

Manage roles and assign permissions.

Method	Endpoint	Description
GET	/api/roles	Get all roles
POST	/api/roles	Create a new role
PUT	/api/roles/{id}	Update a role
DELETE	/api/roles/{id}	Delete a role
POST	/api/roles/{id}/assign-permissions	Assign permissions to role
POST	/api/roles/{id}/unassign-permissions	Unassign permissions from role

---

🖥 User Sessions

Manage WebSocket and chat sessions.

Method	Endpoint	Description
POST	/api/sessions	Create or update session
GET	/api/sessions/user/{userId}	Get sessions for user
GET	/api/sessions/room/{roomId}	Get sessions for room
GET	/api/sessions/active-since	Get active sessions since a specific time
DELETE	/api/sessions/{sessionId}	Delete session by ID

---

👤 Chat User Controller

Endpoints for user registration, login, and management.

Method	Endpoint	Description
POST	/api/users/chat/register	Register a new user
POST	/api/users/chat/login	User login
PATCH	/api/users/chat/{id}/status	Update user status
GET	/api/users/chat	Get all chat users
GET	/api/users/chat/{id}	Get user by ID
PUT	/api/users/chat/{id}	Update user details
DELETE	/api/users/chat/{id}	Delete user
GET	/api/users/chat/top-active	Get top active users
GET	/api/users/chat/active-since	Get users active since timestamp

---

🧍 User Controller

Endpoints for basic user info and search.

Method	Endpoint	Description
POST	/api/users/{id}/status	Update user status
GET	/api/users/user/{id}	Get user info
GET	/api/users/user/active-since	Get users active since timestamp
GET	/api/users/search	Search users
GET	/api/users/by-username/{username}	Get user by username

---

💬 Chat Room Controller

Endpoints for managing chat rooms.

Method	Endpoint	Description
GET	/api/rooms	Get all rooms
POST	/api/rooms	Create new room
GET	/api/rooms/{id}	Get room details
DELETE	/api/rooms/{id}	Delete room
POST	/api/rooms/{id}/join	Join room
POST	/api/rooms/{id}/leave	Leave room
GET	/api/rooms/{id}/count	Count users in room
GET	/api/rooms/user/{userId}	Get rooms by user
GET	/api/rooms/public	Get public rooms

---

💭 Chat Message Controller

Handle chat messages in rooms.

Method	Endpoint	Description
GET	/api/rooms/{roomId}/messages	Get all messages in room
POST	/api/rooms/{roomId}/messages	Send new message
DELETE	/api/rooms/{roomId}/messages	Delete all messages in room
GET	/api/rooms/{roomId}/messages/search	Search messages
GET	/api/rooms/{roomId}/messages/recent	Get recent messages
GET	/api/rooms/{roomId}/messages/last	Get last message

---

🔔 Notification Controller

Manage user and global notifications.

Method	Endpoint	Description
POST	/api/notifications	Create notification
POST	/api/notifications/mark-read/{userId}	Mark notifications as read
GET	/api/notifications/user/{userId}	Get user notifications
GET	/api/notifications/room/{roomId}	Get room notifications
GET	/api/notifications/global	Get global notifications
GET	/api/notifications/count-unread/{userId}	Get unread notification count

---

🔑 Authentication

User authentication and registration.

Method	Endpoint	Description
POST	/api/auth/register	Register new user
POST	/api/auth/login	User login (returns JWT)

---

🔐 Password Reset

Manage password reset process.

Method	Endpoint	Description
POST	/api/auth/password/request	Request password reset
POST	/api/auth/password/confirm	Confirm and set new password

---

📎 Attachments

Manage uploaded files and media.

Method	Endpoint	Description
POST	/api/attachments	Upload attachment
GET	/api/attachments/type	Get attachment types
GET	/api/attachments/room/{roomId}/images	Get images in room
GET	/api/attachments/message/{messageId}	Get attachments for message
DELETE	/api/attachments/message/{messageId}	Delete message attachments
GET	/api/attachments/download/{id}	Download file
DELETE	/api/attachments/{id}	Delete attachment by ID

---

📦 Data Models (Schemas)

• UserRegistrationDTO
• UserDTO
• ChatUserRequest / Response
• RoleRequest / Response
• PermissionRequest / Response
• AuthRequestDTO / AuthResponseDTO
• UserSessionDTO
• CreateRoomDTO / ChatRoomDTO / ChatRoomDetailsDTO
• ChatMessageDTO
• NotificationDTO
• PasswordResetRequestDTO / PasswordResetConfirmDTO
• AttachmentDTO
• AuditLog / AuditLogResponse
• Paging Models: PageUserDTO, PageChatRoomDTO, PageChatMessageDTO, PageableObject, SortObject

---

🧠 Tech Stack

Component	Technology
Backend	Spring Boot 3.x
Security	Spring Security (JWT Authentication)
Database	PostgreSQL / JPA (Hibernate)
Documentation	Swagger UI / OpenAPI 3.1
Build Tool	Maven
Deployment	Docker

---

🧩 Developer Notes

• Default port: 1376
• Admin routes require SUPER_ADMIN role.
• Audit log automatically captures all CRUD changes.
• Swagger UI available at:
  👉 http://localhost:1376/swagger-ui.html

---

🏁 Example Authentication Flow

1. Register new user → /api/auth/register
2. Login → /api/auth/login
   Receive JWT token.
3. Authorize in Swagger with Bearer <token>.
4. Access protected routes (like /api/roles, /api/permissions, etc.).

---

🧑‍💻 Author

Milad Rostami
Java Web Developer | Spring Boot | Security | Reactive Programming

📧 Contact: miladrostami24@gmail.com

---

© 2025 Chat Application REST API — Developed with ❤️ using Spring Boot and JWT Authentication.