Java Spring BootにおけるカスタムAPIレスポンスの習得

When you start building APIs in Spring Boot, things feel simple at first. You return objects, and Spring automatically converts them into JSON. But as your application grows, problems begin to appear: Different APIs return different response formats Error handling becomes messy Frontend developers struggle to handle multiple structures Debugging becomes time-consuming This is where a Custom API Response structure becomes extremely important. In this blog, we will deeply understand not just how to implement it, but also why each part exists and how it helps in real-world projects. Problem with Default API Design Let’s take a real scenario. Case 1: Success API { "id" : 1 , "name" : "Ayush" } Use our Online Code Editor Case 2: Error API { "message" : "User not found" } Use our Online Code Editor Case 3: Validation Error { "errors" : [ "Name is required" , "Email is invalid" ] } Use our Online Code Editor What Breaks Here Now the frontend must write logic like: Check if id exists → success Check if message exists → error Check if errors exists → validation This creates unnecessary conditional handling across web, mobile, and third-party clients. As APIs scale, inconsistent contracts increase maintenance costs. Solution: Standard API Response We fix this by defining a fixed structure: { "data" : {}, "success" : true , "message" : "Request successful" , "errors" : null , "status" : "OK" , "timestamp" : "2026-04-28T10:00:00" } Use our Online Code Editor Why Each Field Exists data → Holds actual response (can be object, list, or null) success → Quick boolean check (frontend friendly) message → Human-readable message errors → Detailed error info (useful for debugging) status → HTTP status for clarity timestamp → Helps in tracking and debugging issues This makes your API predictable and easy to consume. Step 1: StandardResponse Class public class StandardResponse < T > { private T data ; private boolean success ; private String message ; private Object errors ; private HttpStatus status ; private LocalDateTime timestamp ; public StandardResponse ( T data , boolean success , String message , Object errors , HttpStatus status ) { this . data = data ; this . success = success ; this . message = message ; this . errors = errors ; this . status = status ; this . timestamp = LocalDateTime . now (); } } Use our Online Code Editor Deep Explanation Generic <T> Makes the class reusable for any data type Example: String, User, List<User> Object errors Flexible → can store string, list, or map Useful for validation errors timestamp Helps track when API was called Useful in logs and debugging production issues This class becomes the backbone of your API. Step 2: ResponseBuilder (Why It Matters) Without a builder, you would write this everywhere: new StandardResponse <>( data , true , "Success" , null , HttpStatus . OK ); Use our Online Code Editor This is repetitive and error-prone. Solution: public class ResponseBuilder { public static < T > StandardResponse < T > success ( T data , String message ) { return new StandardResponse <>( data , true , message , null , HttpStatus . OK ); } public static < T > StandardResponse < T > error ( String message , Object errors , HttpStatus status ) { return new StandardResponse <>( null , false , message , errors , status ); } } Use our Online Code Editor Why This Matters Reduces code duplication Improves readability Central place to modify response logic Makes your code cleaner Supports cleaner architecture Step 3: Service Layer public StandardResponse < String > getUser () { String user = "Ayush" ; return ResponseBuilder . success ( user , "User fetched successfully" ); } Use our Online Code Editor Why This Is Good Design Business logic stays clean No HTTP logic here Only returns a structured response This follows Separation of Concerns Step 4: Controller Layer @GetMapping ( "/user" ) public ResponseEntity < StandardResponse < String >> getUser () { return ResponseEntity . ok ( userService . getUser ()); } Use our Online Code Editor Why Use ResponseEntity? Allows control over HTTP status Can add headers if needed Makes API more flexible Even though the response has a status inside, the HTTP status is still important. Global Exception Handling (Very Important) Instead of: try { // logic } catch ( Exception e ) { // handle } Use our Online Code Editor Use centralized handling: @RestControllerAdvice public class GlobalExceptionHandler { Use our Online Code Editor Why? Centralized error handling No repeated try-catch Cleaner code Consistent error response Step 6: Validation Handling (Advanced Understanding) When using @Valid, Spring throws: MethodArgumentNotValidException Use our Online Code Editor We handle it like this: List < String > errors = ex . getBindingResult () . getFieldErrors () . stream () . map ( err -> err . getField () + ": " + err . getDefaultMessage ()) . toList (); Use our Online Code Editor What This Does Extracts all validation errors Converts them into readable messages Sends them in response Example Output: "errors" : [ "email: must be valid" , "name: must not be blank" ] Use our Online Code Editor Step 7: Real-World Enhancements 1. Error Codes Instead of just a message: "errorCode" : "USER_NOT_FOUND" Use our Online Code Editor Helps frontend and logging systems. 2. Request ID (Tracing) In microservices: "requestId" : "abc-123-xyz" Use our Online Code Editor Helps track requests across services. 3. Pagination Support { "data" : { "content" : [], "page" : 1 , "size" : 10 , "totalElements" : 100 } } Use our Online Code Editor Important for large datasets. 4. Execution Time Track performance: long start = System . currentTimeMillis (); Use our Online Code Editor Helps optimize slow APIs. Common Mistakes to Avoid Returning raw entities directly Mixing multiple response formats Not handling exceptions globally Ignoring validation errors Hardcoding messages everywhere Have a great one!!! Author: Ayush Shrivastava Thank you for being a part of the community Before you go: Whenever you’re ready There are 4 ways we can help you become a great backend engineer: The MB Platform: Join thousands of backend engineers learning backend engineering. Build real-world backend projects, learn from expert-vetted courses and roadmaps, track your learning and set schedules, and solve backend engineering tasks, exercises, and challenges. The MB Academy: The “MB Academy” is a 6-month intensive Advanced Backend Engineering Boot Camp to produce great backend engineers. Join Backend Weekly: If you like posts like this, you will absolutely enjoy our exclusive weekly newsletter, sharing exclusive backend engineering resources to help you become a great Backend Engineer. Get Backend Jobs: Find over 2,000+ Tailored International Remote Backend Jobs or Reach 50,000+ backend engineers on the #1 Backend Engineering Job Board. When you start building APIs in Spring Boot, things feel simple at first. You return objects, and Spring automatically converts them into JSON. But as your application grows, problems begin to appear: Different APIs return different response formats Error handling becomes messy Frontend developers struggle to handle multiple structures Debugging becomes time-consuming This is where a Custom API Response structure becomes extremely important. In this blog, we will deeply understand not just how to implement it, but also why each part exists and how it helps in real-world projects. Problem with Default API Design Let’s take a real scenario. Case 1: Success API { "id" : 1 , "name" : "Ayush" } Use our Online Code Editor Case 2: Error API { "message" : "User not found" } Use our Online Code Editor Case 3: Validation Error { "errors" : [ "Name is required" , "Email is invalid" ] } Use our Online Code Editor What Breaks Here Now the frontend must write logic like: Check if id exists → success Check if message exists → error Check if errors exists → validation This creates unnecessary conditional handling across web, mobile, and third-party clients. As APIs scale, inconsistent contracts increase maintenance costs. Solution: Standard API Response We fix this by defining a fixed structure: { "data" : {}, "success" : true , "message" : "Request successful" , "errors" : null , "status" : "OK" , "timestamp" : "2026-04-28T10:00:00" } Use our Online Code Editor Why Each Field Exists data → Holds actual response (can be object, list, or null) success → Quick boolean check (frontend friendly) message → Human-readable message errors → Detailed error info (useful for debugging) status → HTTP status for clarity timestamp → Helps in tracking and debugging issues This makes your API predictable and easy to consume. Step 1: StandardResponse Class public class StandardResponse < T > { private T data ; private boolean success ; private String message ; private Object errors ; private HttpStatus status ; private LocalDateTime timestamp ; public StandardResponse ( T data , boolean success , String message , Object errors , HttpStatus status ) { this . data = data ; this . success = success ; this . message = message ; this . errors = errors ; this . status = status ; this . timestamp = LocalDateTime . now (); } } Use our Online Code Editor Deep Explanation Generic <T> Makes the class reusable for any data type Example: String, User, List<User> Object errors Flexible → can store string, list, or map Useful for validation errors timestamp Helps track when API was called Useful in logs and debugging production issues This class becomes the backbone of your API. Step 2: ResponseBuilder (Why It Matters) Without a builder, you would write this everywhere: new StandardResponse <>( data , true , "Success" , null , HttpStatus . OK ); Use our Online Code Editor This is repetitive and error-prone. Solution: public class ResponseBuilder { public static < T > StandardResponse < T > success ( T data , String message ) { return new StandardResponse <>( data , true , message , null , HttpStatus . OK ); } public static < T > Sta