v3.0.1 - 🚨 DEPRECATED & RELOCATED to OG4Dev

⚠️ This Project Has Been Relocated!

We are excited to announce that this project has been rebranded and relocated to our new, official organization: OG4Dev.

To provide better long-term support, professional maintenance, and a unified namespace for our tools, the api-response library is now officially the og4dev-spring-response library.

🚨 IMPORTANT: This repository (io.github.pasinduog:api-response) is now DEPRECATED. Version 3.0.1 is the final release here. No further updates, bug fixes, or features will be pushed to this artifact.

---

🚀 Where to go next?

Please continue your development and access all future updates at our new home:

• New GitHub Repository: https://github.com/OG4Dev/og4dev-spring-response
• New Maven Central Artifact: io.github.og4dev:og4dev-spring-response

---

🔄 How to Migrate (It takes 10 seconds!)

The API and core functionality are 100% compatible. You do not need to change any of your Java code. You only need to update your dependency coordinates.

If you use Maven:

Remove the old dependency:

<dependency>
    <groupId>io.github.pasinduog</groupId>
    <artifactId>api-response</artifactId>
    <version>3.0.1</version>
</dependency>

Add the new dependency:

<dependency>
    <groupId>io.github.og4dev</groupId>
    <artifactId>og4dev-spring-response</artifactId>
    <version>1.0.0</version>
</dependency>

If you use Gradle:

// REMOVE THIS
implementation 'io.github.pasinduog:api-response:3.0.1'

// ADD THIS
implementation 'io.github.og4dev:og4dev-spring-response:1.0.0'

---

🙏 Thank You!

Thank you for supporting this project! We look forward to seeing you over at the new [OG4Dev Spring Response](https://github.com/OG4Dev/og4dev-spring-response) repository. If you haven't already, please drop a ⭐ on the new repo!

Full Changelog: v3.0.0...v3.0.1

v2.0.1 - Success Response Refinement & Cleaner Payloads

We are happy to announce the release of API Response v2.0.1! 🎉

This release focuses on optimizing response payloads, improving the separation of concerns, and providing cleaner JSON structures for your successful API calls.

⚠️ Note: This release includes a structural change to success responses. Please review the migration notes below before upgrading.

🚀 What's New & Changed?

🧹 Removed Trace ID from Success Responses

To drastically clean up success payloads and reduce JSON size, we have removed the traceId field from standard success responses (ApiResponse).

• Why? Trace IDs are primarily meant for tracking issues. Including them in every single successful response unnecessarily bloated the payload.
• Errors still have them: Trace IDs are still automatically included in all error responses (ProblemDetail format) generated by the GlobalExceptionHandler.
• Tracing Success Flows: If you need distributed tracing for success flows, we recommend using HTTP headers in combination with the provided TraceIdFilter.

✨ Improvements

• Cleaner JSON Payloads: Your success responses are now laser-focused on essential data (status, message, content, timestamp).
• Better Separation of Concerns: Error tracking belongs in error payloads, while distributed tracing belongs in HTTP headers.
• Reduced Bandwidth: Smaller response bodies mean faster API responses and reduced bandwidth consumption.

---

🔄 Migration Guide (v2.0.0 ➡️ v2.0.1)

If your client applications or tests were explicitly asserting the existence of a traceId in success responses, you will need to update them.

❌ Before (v2.0.0 Success Response):

{
  "status": 200,
  "traceId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "User found",
  "content": { ... },
  "timestamp": "2026-02-15T10:30:45.123Z"
}

✅ After (v2.0.1 Success Response):

{
  "status": 200,
  "message": "User found",
  "content": { ... },
  "timestamp": "2026-02-15T10:30:45.123Z"
}

(Error responses remain unchanged and will still include the traceId)

---

📦 Installation

Update your dependency to version 2.0.1:

Maven

<dependency>
    <groupId>io.github.pasinduog</groupId>
    <artifactId>api-response</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle

implementation 'io.github.pasinduog:api-response:2.0.1'

---

Full Changelog: v2.0.0...v2.0.1

v3.0.0 - Major Release: Pure Java, RFC 9457 & Enhanced Exception Handling

We are thrilled to announce the release of API Response v3.0.0! 🎉

This is a major milestone that completely removes all external dependencies, upgrades our error handling to the latest industry standards, and makes the library incredibly lightweight and robust.

🚨 IMPORTANT: This is a MAJOR release with BREAKING CHANGES. Please read the migration notes below before upgrading from v2.0.0 or v1.3.0.

⚠️ Breaking Changes

1. ❌ Lombok Dependency Removed: The library is now 100% Pure Java. We have moved away from Lombok's @Builder to a custom builder pattern implementation. This eliminates annotation processing overhead and potential IDE plugin conflicts.
2. ❌ traceId Removed from Success Responses: To keep success payloads clean, traceId is no longer included in standard ApiResponse JSON bodies. Trace IDs are now exclusively injected into error responses (ProblemDetail) for debugging. (You can still use MDC/Headers for success tracing).

✨ New Features

• 🛡️ 10 Comprehensive Exception Handlers: We've expanded the GlobalExceptionHandler to automatically cover 6 new critical scenarios (Total 10):

• HttpMessageNotReadableException (Malformed JSON)

• MissingServletRequestParameterException (Missing Params)

• NoResourceFoundException (404 Not Found)

• HttpRequestMethodNotSupportedException (405 Method Not Allowed)

• HttpMediaTypeNotSupportedException (415 Unsupported Media Type)

• NullPointerException (with safe stack trace logging)

• 📋 RFC 9457 Compliance: Upgraded error formatting from RFC 7807 to the latest RFC 9457 ProblemDetail standard.

• 🔍 Distributed Tracing Filter: Added TraceIdFilter for automatic trace ID generation, MDC integration, and seamless log correlation across microservices.

• 📚 100% Javadoc Coverage: Achieved a perfectly clean build with zero Javadoc warnings. Every class, method, and constructor is now explicitly documented.

🛠️ Improvements

• Zero External Dependencies: Only requires spring-boot-starter-web (provided scope). No more transitive dependency worries!
• Thread-Safe by Design: Fully immutable response objects with a minimal memory footprint (~200 bytes per response).
• Spring Boot 4.0.2 Ready: Fully tested and verified compatibility with Spring Boot 3.2.0 through 4.0.2.

---

🔄 Quick Migration Guide (v2.0.0 ➡️ v3.0.0)

If you were using the static factory methods (success(), created(), status()), no code changes are required!

If you were manually building responses using the builder, update your syntax:

❌ Before (v2.0.0):

ApiResponse<User> response = ApiResponse.<User>builder()
    .message("Success")
    .data(user)
    .build();

✅ After (v3.0.0):

ApiResponse<User> response = new ApiResponse.ApiResponseBuilder<User>()
    .message("Success")
    .content(user) // Note: "data" was renamed to "content"
    .build();

---

📦 Installation

Maven:

<dependency>
    <groupId>io.github.pasinduog</groupId>
    <artifactId>api-response</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle:

implementation 'io.github.pasinduog:api-response:3.0.0'

What's Changed

• Feature/v3.0.0 by @PasinduOG in #13
• Dev by @PasinduOG in #14

Full Changelog: v2.0.0...v3.0.0

v2.0.0 - Major Release: Production-Ready Exception Handling & RFC 9457 Compliance

✨ Features

• 🎯 Consistent Structure - All responses follow the same format: status, traceId, message, content, timestamp
• 🔒 Type-Safe - Full generic type support with compile-time type checking
• 🔍 Distributed Tracing - Auto-generated UUID trace IDs with MDC integration for request tracking (Enhanced in v2.0.0)
• ⏰ Auto Timestamps - Automatic RFC 3339 UTC formatted timestamps on every response
• 🏭 Factory Methods - Clean static methods: success(), created(), status()
• 🚀 Zero Config - Spring Boot Auto-Configuration for instant setup (Enhanced in v1.3.0)
• 🪶 Lightweight - Only ~10KB JAR with provided dependencies (Spring Web + Lombok)
• 📦 Immutable - Thread-safe with final fields
• 🔌 Spring Native - Built on ResponseEntity and HttpStatus
• 📋 RFC 9457 Compliance - Standard ProblemDetail format (supersedes RFC 7807) (Updated in v2.0.0)
• 📚 Complete JavaDoc - Every class fully documented with explicit constructor documentation (New in v2.0.0)
• 🛡️ Comprehensive Exception Handling - 10 built-in handlers covering all common scenarios (Enhanced in v2.0.0)
  • ✅ Validation errors (@Valid annotations)
  • ✅ Type mismatches (wrong parameter types)
  • ✅ Malformed JSON (invalid request bodies)
  • ✅ Missing parameters (required @RequestParam)
  • ✅ 404 Not Found (missing endpoints/resources)
  • ✅ 405 Method Not Allowed (wrong HTTP method)
  • ✅ 415 Unsupported Media Type (invalid Content-Type)
  • ✅ Null pointer exceptions
  • ✅ Custom business exceptions (ApiException)
  • ✅ General unexpected errors
• 🎭 Custom Business Exceptions - Abstract ApiException class for domain-specific errors (New in v1.2.0)
• ✅ Validation Support - Automatic @Valid annotation error handling

What's Changed

• Downgrade to Spring Boot version for keep the v1.3.0 stable by @PasinduOG in #1
• Feature/v2 by @PasinduOG in #2
• Feature/v2 by @PasinduOG in #3
• Feature/v2.0.0 by @PasinduOG in #4
• docs(readme): add SkillIcons technology stack logos by @PasinduOG in #5
• docs: enhance Apache 2.0 License documentation and contributor guidelines by @PasinduOG in #6
• v2.0.0 Released by @PasinduOG in #7
• docs: update README for v2.0.0 release by @PasinduOG in #8

New Contributors

• @PasinduOG made their first contribution in #1

Full Changelog: v1.3.0...v2.0.0

v1.3.0 - Auto-Configuration Support & Seamless Integration

✨ Features

• 🎯 Consistent Structure - All responses follow the same format: status, traceId, message, data, timestamp
• 🔒 Type-Safe - Full generic type support with compile-time type checking
• 🔍 Distributed Tracing - Auto-generated UUID trace IDs for request tracking (New in v1.2.0)
• ⏰ Auto Timestamps - Automatic ISO-8601 UTC formatted timestamps on every response
• 🏭 Factory Methods - Clean static methods: success(), created(), status()
• 🚀 Zero Config - Spring Boot Auto-Configuration for instant setup (Enhanced in v1.3.0)
• 🪶 Lightweight - Only ~10KB JAR with provided dependencies (Spring Web + Lombok)
• 📦 Immutable - Thread-safe with final fields
• 🔌 Spring Native - Built on ResponseEntity and HttpStatus
• 🛡️ Global Exception Handler - Built-in ProblemDetail RFC 7807 error handling
• 🎭 Custom Business Exceptions - Abstract ApiException class for domain-specific errors (New in v1.2.0)
• ✅ Validation Support - Automatic @Valid annotation error handling

Full Changelog: v1.2.0...v1.3.0

v1.2.0 - Feature Release: Customizable Exception Architecture

✨ Features

• 🎯 Consistent Structure - All responses follow the same format: status, traceId, message, data, timestamp
• 🔒 Type-Safe - Full generic type support with compile-time type checking
• 🔍 Distributed Tracing - Auto-generated UUID trace IDs for request tracking (New in v1.2.0)
• ⏰ Auto Timestamps - Automatic ISO-8601 UTC formatted timestamps on every response
• 🏭 Factory Methods - Clean static methods: success(), created(), status()
• 🚀 Zero Config - Works immediately with no configuration required
• 🪶 Lightweight - Only ~15KB with minimal dependencies (Spring Web + Lombok)
• 📦 Immutable - Thread-safe with final fields
• 🔌 Spring Native - Built on ResponseEntity and HttpStatus
• 🛡️ Global Exception Handler - Built-in ProblemDetail RFC 7807 error handling
• 🎭 Custom Business Exceptions - Abstract ApiException class for domain-specific errors (New in v1.2.0)
• ✅ Validation Support - Automatic @Valid annotation error handling

Full Changelog: v1.1.0...v1.2.0

v1.1.0 - Production Ready: RFC 7807 Error Handling & Full Documentation

✨ Features

• 🎯 Consistent Structure - All responses follow the same format: message, data, timestamp
• 🔒 Type-Safe - Full generic type support with compile-time type checking
• ⏰ Auto Timestamps - Automatic ISO-8601 formatted timestamps on every response
• 🏭 Factory Methods - Clean static methods: success(), created(), status()
• 🚀 Zero Config - Works immediately with no configuration required
• 🪶 Lightweight - Only ~15KB with minimal dependencies (Spring Web + Lombok)
• 📦 Immutable - Thread-safe with final fields
• 🔌 Spring Native - Built on ResponseEntity and HttpStatus
• 🛡️ Global Exception Handler - Built-in ProblemDetail RFC 7807 error handling
• ✅ Validation Support - Automatic @Valid annotation error handling

Full Changelog: v1.0.0...v1.1.0

v1.0.0 - Initial Release

🚀 Features

• Consistent Structure: Every response includes a message, data, and timestamp.
• Static Factory Methods: Easy-to-use methods like success(), created(), and status().
• Type Safety: Built using Java Generics (<T>) to support any data type.
• Spring Boot 3+ Compatible: Optimized for modern Spring Boot applications.

Full Changelog: https://github.com/PasinduOG/api-response/commits/v1.0.0