REST API: error handling, pagination, versioning, idempotency, content negotiation

package com.bank.exception;

import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.slf4j.MDC;
import java.net.URI;
import java.time.Instant;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(AccountNotFoundException.class)
    public ProblemDetail handleNotFound(AccountNotFoundException e) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND, e.getMessage());
        pd.setType(URI.create("https://api.nbi.in/problems/account-not-found"));
        pd.setTitle("Account Not Found");
        pd.setProperty("traceId", MDC.get("traceId"));
        return pd;
    }

    @ExceptionHandler(InsufficientFundsException.class)
    public ProblemDetail handleInsufficient(InsufficientFundsException e) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.UNPROCESSABLE_ENTITY, e.getMessage());
        pd.setType(URI.create("https://api.nbi.in/problems/insufficient-funds"));
        pd.setTitle("Insufficient Funds");
        pd.setProperty("traceId", MDC.get("traceId"));
        return pd;
    }
}

package com.bank.controller;

import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/api/v1/accounts/{accountId}/transactions")
public class TransactionController {

    // Cursor pagination: fast at any depth, stable under concurrent inserts.
    @GetMapping
    public CursorPage<TransactionResponse> list(
            @PathVariable String accountId,
            @RequestParam(required = false) String cursor,
            @RequestParam(defaultValue = "20") int limit) {
        return transactionService.findAfter(accountId, cursor, limit);
    }
}

// Response:
// {
//   "content": [{...}, {...}],
//   "nextCursor": "eyJpZCI6IlRYTi0zOTk4MCJ9",
//   "limit": 20,
//   "hasNext": true
// }

// URL path versioning: clearest for clients and routing.
@RestController
@RequestMapping("/api/v1/accounts")
public class AccountControllerV1 {
    @GetMapping("/{id}")
    public AccountResponseV1 get(@PathVariable String id) {
        return accountService.getV1(id);
    }
}

@RestController
@RequestMapping("/api/v2/accounts")
public class AccountControllerV2 {
    @GetMapping("/{id}")
    public AccountResponseV2 get(@PathVariable String id) {
        return accountService.getV2(id); // New response shape
    }
}

package com.bank.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;

@RestController
@RequestMapping("/api/v1/transfers")
public class TransferController {

    @PostMapping
    public ResponseEntity<TransferResponse> create(
            @RequestHeader("Idempotency-Key") String key,
            @Valid @RequestBody TransferRequest req) {
        // First call: process transfer, store result under key.
        // Retry with same key: return stored result, no new transfer.
        return ResponseEntity.ok(transferService.createOnce(key, req));
    }
}

// Content negotiation: one endpoint, multiple formats.
@GetMapping(value = "/{id}",
        produces = {"application/json", "application/xml"})
public AccountResponse get(@PathVariable String id) {
    return accountService.findById(id);
    // Spring picks JSON or XML based on the Accept header.
    // If Accept is something unsupported, Spring returns 406.
}

// All five in one flow:
// 1. Versioned URL:          /api/v1/transfers
// 2. Content negotiation:    Accept: application/json
// 3. Idempotency:            Idempotency-Key: rent-oct-2026
// 4. Error handling:         422 + Problem Details on insufficient funds
// 5. Pagination:             GET /api/v1/transactions?cursor=TXN-500&limit=20

// POST /api/v1/transfers
// Headers:
//   Accept: application/json
//   Content-Type: application/json
//   Idempotency-Key: rent-oct-2026
// Body: {"from": "SAV2001", "to": "SAV2002", "amount": 50000}
// Response: 201 Created  or  422 + Problem Details

// Wrong: 200 for error, no versioning, no idempotency key.
@PostMapping("/transfer")
public Map<String, Object> transfer(@RequestBody TransferRequest req) {
    try {
        transferService.create(req);
        return Map.of("success", true);
    } catch (Exception e) {
        return Map.of("success", false, "error", e.getMessage()); // 200 + error in body!
    }
}

// Correct: proper status, versioning, idempotency, Problem Details.
@PostMapping("/api/v1/transfers")
public ResponseEntity<TransferResponse> create(
        @RequestHeader("Idempotency-Key") String key,
        @Valid @RequestBody TransferRequest req) {
    TransferResponse resp = transferService.createOnce(key, req);
    return ResponseEntity.created(URI.create("/api/v1/transfers/" + resp.id()))
            .body(resp);
}
// Errors are handled centrally by @RestControllerAdvice with Problem Details.