API Response Models

A response wrapper provides a consistent format for all API responses, making it easier for clients to handle success and error cases.

Basic Response Wrapper

public class ApiResponse<T> {
    private boolean success;
    private String message;
    private T data;
    private LocalDateTime timestamp;

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.success = true;
        response.message = "Success";
        response.data = data;
        response.timestamp = LocalDateTime.now();
        return response;
    }

    public static <T> ApiResponse<T> success(String message, T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.success = true;
        response.message = message;
        response.data = data;
        response.timestamp = LocalDateTime.now();
        return response;
    }

    public static <T> ApiResponse<T> error(String message) {
        ApiResponse<T> response = new ApiResponse<>();
        response.success = false;
        response.message = message;
        response.timestamp = LocalDateTime.now();
        return response;
    }

    // Getters and Setters
}

Usage in Controller

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<ProductDto>> getProduct(@PathVariable Long id) {
        ProductDto product = productService.getProduct(id);
        return ResponseEntity.ok(ApiResponse.success(product));
    }

    @PostMapping
    public ResponseEntity<ApiResponse<ProductDto>> createProduct(
            @Valid @RequestBody CreateProductRequest request) {
        ProductDto created = productService.createProduct(request);
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(ApiResponse.success("Product created", created));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<ApiResponse<Void>> deleteProduct(@PathVariable Long id) {
        productService.deleteProduct(id);
        return ResponseEntity.ok(ApiResponse.success("Product deleted", null));
    }
}

Paginated Response

public class PagedResponse<T> {
    private List<T> content;
    private int page;
    private int size;
    private long totalElements;
    private int totalPages;
    private boolean first;
    private boolean last;

    public static <T> PagedResponse<T> of(Page<T> page) {
        PagedResponse<T> response = new PagedResponse<>();
        response.content = page.getContent();
        response.page = page.getNumber();
        response.size = page.getSize();
        response.totalElements = page.getTotalElements();
        response.totalPages = page.getTotalPages();
        response.first = page.isFirst();
        response.last = page.isLast();
        return response;
    }
}

Standard JSON Format

// Success
{
    "success": true,
    "message": "Success",
    "data": {
        "id": 1,
        "name": "Widget",
        "price": 29.99
    },
    "timestamp": "2024-01-15T10:30:00"
}

// Paginated
{
    "content": [...],
    "page": 0,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8,
    "first": true,
    "last": false
}

// Error
{
    "success": false,
    "message": "Validation failed",
    "details": ["name: is required", "price: must be positive"],
    "timestamp": "2024-01-15T10:30:00"
}

Design Principles

• Use nouns, not verbs
• Plural resource names
• Consistent naming conventions
• Proper HTTP status codes

Versioning

• URI versioning (/v1/resource)
• Header versioning
• Deprecation policy

Documentation

• OpenAPI/Swagger specs
• Request/Response examples
• Error code documentation
• Rate limit documentation

Key Points

• Understanding API Response Models is essential for production systems
• Always consider scalability and maintainability
• Test thoroughly before deploying to production
• Monitor performance and set up alerting

Common Patterns

1. Validation: Always validate input at the boundary
2. Error Handling: Use structured error responses
3. Logging: Log key events for debugging
4. Testing: Unit, integration, and load tests
5. Documentation: Keep docs updated with code changes