Implementing API Idempotency with Spring Boot, Redis, and Custom Annotations

In real‑world development, an exposed API may receive many repeated requests, so ensuring idempotency—where multiple executions have the same effect as a single execution—is essential to prevent duplicate data modifications.

The article outlines common idempotency techniques: unique database indexes, token mechanisms, pessimistic/optimistic locks, and pre‑check‑then‑execute logic.

It then introduces a Redis‑based solution, showing how to set up a Redis service and use @Component public class RedisService { ... } with methods for set, setEx, exists, get, and remove.

A custom annotation

@Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface AutoIdempotent { }

is defined to mark methods that require automatic idempotency.

The token service interface and implementation are presented, illustrating token creation with a UUID stored in Redis (expiration 10,000 seconds) and token validation that checks the request header or parameter, throws exceptions on missing or reused tokens, and removes the token after successful validation.

Web configuration adds an AutoIdempotentInterceptor to the Spring MVC interceptor chain. The interceptor inspects handler methods for the @AutoIdempotent annotation, invokes the token service’s checkToken method, and returns JSON error responses when validation fails.

Sample controller code demonstrates obtaining a token via @PostMapping("/get/token") and a protected endpoint @AutoIdempotent @PostMapping("/test/Idempotence") that can be called only once per token.

Using Postman, the first request succeeds, while subsequent requests with the same token return a “repetitive operation” error, confirming the idempotency enforcement.

The conclusion emphasizes that this Redis‑backed, annotation‑driven approach provides an elegant, automated way to guarantee idempotent API calls, improving data integrity and reducing unnecessary load.