Designing Clean API Responses in Java: From JSON Structure to Global Wrappers

Overview

In modern mobile‑internet projects that adopt micro‑service architecture and front‑end/back‑end separation, a clear API response design is essential.

System Architecture

The diagram shows a typical overall system layout. The author notes that the diagram is simplified and omits gateways, caches, or message middleware because the focus is on API interfaces.

PART 01 – Interface Interaction

Front‑end calls a URL following RESTful conventions and passes common headers such as app version, api version, device . The back‑end processes the request and returns data.

PART 02 – Return Format

Responses are wrapped in a JSON object with three fields:

{
    // return status code
    code: integer,
    // return message description
    message: string,
    // return data
    data: object
}

The code field can be customized; the author suggests borrowing the idea of HTTP status codes and grouping custom codes:

#1000‑1999  Parameter errors
#2000‑2999  User errors
#3000‑3999  Interface exceptions

Images illustrate the code ranges.

The message field provides a user‑friendly description of the error, typically defined alongside the code.

The data field contains the business‑specific payload in JSON format.

PART 03 – Designing a Result Wrapper

The author introduces a Result class to encapsulate code, message, and data. Controller methods initially return Result.success(order) or Result.failure(...), but this adds boilerplate.

Static helper methods are added to make the code more readable, and the controller layer is refactored to use the wrapper.

However, the author points out drawbacks: the wrapper hides business semantics, the success/failure methods are redundant, and validation should be handled by frameworks like Hibernate Validator.

Ultimately, returning the raw business object (e.g., an order) is recommended.

PART 04 – Implementation Plan

To automate wrapping, the following steps are proposed:

Define a custom annotation @ResponseResult to mark methods whose return values need wrapping.

Create an interceptor that checks for the annotation on each request.

Implement ResponseBodyAdvice together with @ControllerAdvice to rewrite the response body when needed.

Images show the annotation definition, interceptor logic, and the response‑rewriting mechanism.

Exception handling can be added in the same advice; the article leaves this as an exercise.

PART 05 – Summary

The presented solution yields a concise and elegant API response pattern, while still allowing further improvements such as caching the annotation lookup to avoid reflection on every request.