Skip to content
Designing Robust External APIs: RESTful, Security, Idempotency & Rate Limiting

Designing Robust External APIs: RESTful, Security, Idempotency & Rate Limiting

This comprehensive guide covers production-grade external API design including RESTful conventions, unified response structures, security mechanisms (HMAC signatures, replay prevention), idempotency patterns, rate limiting, circuit breaking, version management, and monitoring—with practical Java/Spring code implementations and interview-focused technical deep-dives.

Rain's Path to Java Mastery
Rain's Path to Java Mastery
Rain's Path to Java Mastery

Designing Production-Grade External APIs: Core Principles and Implementation

The Golden Triangle of API Design

All API design rests on three foundational principles; deviating from them yields APIs that nobody wants to use.

Golden Triangle principles diagram
Golden Triangle principles diagram

Interface Naming and Conventions

Strictly adhere to RESTful style, the de facto industry standard that drastically reduces communication overhead:

Resources use plural nouns: /users, /orders, /products.

HTTP verbs indicate operations: GET (query), POST (create), PUT (full update), PATCH (partial update), DELETE (delete).

Prohibit verbs in paths: ❌ /getUser, ✅ /users/{id}.

Use hyphens as path separators: ❌ /userInfo, ✅ /user-info.

Uniform lowercase to avoid case-sensitivity issues.

Request and Response Design

The most error-prone area; a unified format matters more than anything.

1. Unified Response Structure

{
  "code": 200,          // Business status code, not HTTP status code
  "message": "success", // Prompt message
  "data": {},           // Business data
  "timestamp": 1717888888888 // Server timestamp
}

2. Standard Pagination Design

All list endpoints must support pagination to prevent large datasets from overwhelming the service:

GET /users?pageNum=1&pageSize=20&sort=createTime,desc

Response example:

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "list": [...],
    "pageNum": 1,
    "pageSize": 20,
    "pages": 5
  }
}

3. Critical Considerations

Parameter validation : All input parameters must be validated at the Controller layer using JSR-380 annotations ( @NotNull, @Size, etc.).

Sensitive field masking : Phone numbers, ID cards, bank card numbers must return masked data.

No internal exception stacks : Production exception details leak system architecture and give attackers opportunities.

Security Design

Security is the lifeline of external APIs; an API without security is running naked.

Security architecture diagram
Security architecture diagram

Core security measures:

Enforce HTTPS : All external endpoints must use HTTPS; plain HTTP is forbidden.

Signature mechanism : Request parameters + timestamp + nonce + secret generate a signature to prevent parameter tampering.

Replay attack prevention : Signature validity typically 5-15 minutes, combined with nonce deduplication.

Authentication : Prefer stateless JWT; add second-factor verification for highly sensitive operations.

Authorization : RBAC model for fine-grained per-endpoint access control.

Performance and Availability Design

A good API must not only work but be usable and durable.

The following table maps common problems to solutions and implementation highlights:

High concurrency → Rate limiting: Token bucket algorithm, Redis-based distributed rate limiting.

Service avalanche → Circuit breaking & degradation: Use Sentinel/Hystrix; non-core endpoints degrade directly.

Duplicate submission → Idempotency: Unique request ID + deduplication table; all write operations must guarantee idempotency.

Slow queries → Caching: Hot data into Redis with reasonable TTL.

Large data volumes → Batch processing: Export and batch query endpoints must process in batches to avoid OOM.

Idempotency design is paramount : All write operations (POST/PUT/DELETE) must guarantee idempotency to prevent duplicate orders, duplicate deductions, and other serious business issues.

Version Management

Once published, an API cannot be changed arbitrarily; version control is key to compatibility:

Recommended: URL path versioning : /api/v1/users, /api/v2/users.

Not recommended: parameter versioning ( ?version=1) or header versioning.

Retain old versions for at least 3-6 months, giving callers ample migration time.

Deprecated endpoints should include Deprecation and Sunset headers as warnings.

Documentation and Monitoring

API documentation : Mandatory Swagger/OpenAPI 3.0; docs must include functional description, request/response parameter details, success/failure examples, and error code reference table.

Monitoring and alerting : Track core metrics: QPS, response time, error rate; slow API top 10; abnormal call counts; rate limiting and circuit breaker trigger counts.

Summary

A well-designed external API should behave like an elegant waiter :

Speaks clearly (naming conventions)

Friendly attitude (unified responses)

Safe and reliable (protection in place)

Quick response (excellent performance)

Keeps up with the times (version iteration)

It is not only a bridge between systems but also the face of the technical team. A poorly designed API makes callers suffer; a well-designed one greatly improves development efficiency and system stability.

Core Code Implementations and Technical Highlights

The following five modules showcase the most critical, production-ready code for external API design.

1. Unified Response Envelope + Global Exception Handling (Foundation)

Technical highlight : Generic encapsulation + global exception interception eliminates scattered response construction code and unifies all exception return formats.

// 1. Common response envelope
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;
    private long timestamp;

    // Static factory methods for business code
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(200, "success", data, System.currentTimeMillis());
    }

    public static <T> ApiResponse<T> fail(int code, String message) {
        return new ApiResponse<>(code, message, null, System.currentTimeMillis());
    }
}

// 2. Global exception handler
@RestControllerAdvice
public class GlobalExceptionHandler {

    // Business exception
    @ExceptionHandler(BusinessException.class)
    public ApiResponse<Void> handleBusinessException(BusinessException e) {
        return ApiResponse.fail(e.getCode(), e.getMessage());
    }

    // Validation exception
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<Void> handleValidationException(MethodArgumentNotValidException e) {
        String errorMsg = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        return ApiResponse.fail(400, "Parameter error: " + errorMsg);
    }

    // Catch-all (never return exception stack)
    @ExceptionHandler(Exception.class)
    public ApiResponse<Void> handleException(Exception e) {
        log.error("System exception", e); // Internal full logging
        return ApiResponse.fail(500, "System busy, please try again later");
    }
}

2. Signature Verification Utility (Security Core)

Technical highlight : Supports anti-tampering + anti-replay; production-standard implementation.

@Component
public class SignUtils {
    private static final String SIGN_SECRET = "your-secret-key"; // From config center
    private static final long SIGN_EXPIRE_TIME = 5 * 60 * 1000; // 5-minute validity

    // Generate signature
    public String generateSign(Map<String, String> params, String timestamp, String nonce) {
        // 1. Sort parameters lexicographically
        String sortedParams = params.entrySet().stream()
                .sorted(Map.Entry.comparingByKey())
                .map(entry -> entry.getKey() + "=" + entry.getValue())
                .collect(Collectors.joining("&"));

        // 2. Concatenate sign string: sortedParams + timestamp + nonce + secret
        String signStr = sortedParams + timestamp + nonce + SIGN_SECRET;

        // 3. MD5 encrypt and uppercase
        return DigestUtils.md5DigestAsHex(signStr.getBytes()).toUpperCase();
    }

    // Verify signature + anti-replay
    public boolean verifySign(Map<String, String> params, String timestamp, String nonce, String sign) {
        // 1. Check timestamp expiry
        long requestTime = Long.parseLong(timestamp);
        if (System.currentTimeMillis() - requestTime > SIGN_EXPIRE_TIME) {
            return false;
        }

        // 2. Check nonce existence (anti-replay)
        String redisKey = "nonce:" + nonce;
        if (redisTemplate.hasKey(redisKey)) {
            return false;
        }

        // 3. Verify signature
        String serverSign = generateSign(params, timestamp, nonce);
        if (!serverSign.equals(sign)) {
            return false;
        }

        // 4. Store in Redis with same TTL as signature validity
        redisTemplate.opsForValue().set(redisKey, "1", SIGN_EXPIRE_TIME, TimeUnit.MILLISECONDS);
        return true;
    }
}

3. Idempotency Annotation + AOP (Non-Invasive Design)

Technical highlight : Annotation-driven + AOP; zero business code intrusion; supports custom idempotency TTL.

// 1. Idempotency annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
    long expireTime() default 10 * 60 * 1000; // Default 10 minutes
}

// 2. AOP aspect implementation
@Aspect
@Component
public class IdempotentAspect {
    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    @Around("@annotation(idempotent)")
    public Object around(ProceedingJoinPoint point, Idempotent idempotent) throws Throwable {
        // 1. Get unique request ID (recommend from header, frontend-generated)
        HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest();
        String requestId = request.getHeader("X-Request-Id");
        if (StringUtils.isEmpty(requestId)) {
            throw new BusinessException(400, "Missing request unique identifier");
        }

        // 2. Redis atomic check for prior execution
        String redisKey = "idempotent:" + requestId;
        Boolean success = redisTemplate.opsForValue()
                .setIfAbsent(redisKey, "1", idempotent.expireTime(), TimeUnit.MILLISECONDS);

        if (Boolean.FALSE.equals(success)) {
            throw new BusinessException(409, "Duplicate submission not allowed");
        }

        // 3. Execute original method
        try {
            return point.proceed();
        } catch (Exception e) {
            // On exception, delete key to allow retry
            redisTemplate.delete(redisKey);
            throw e;
        }
    }
}

// 3. Business usage example
@PostMapping("/orders")
@Idempotent(expireTime = 30 * 60 * 1000) // Order no duplicate submit within 30 minutes
public ApiResponse<OrderVO> createOrder(@RequestBody @Valid CreateOrderRequest request) {
    Order order = orderService.createOrder(request);
    return ApiResponse.success(convert(order));
}

4. Distributed Rate Limiting Annotation + AOP

Technical highlight : Redis-based token bucket algorithm; supports custom rate limiting rules; effective in cluster environments.

// 1. Rate limiting annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
    int limit() default 100; // Requests per second
    int burst() default 200; // Burst traffic ceiling
}

// 2. AOP aspect implementation
@Aspect
@Component
public class RateLimitAspect {
    @Autowired
    private RedisTemplate<String, String> redisTemplate;
    private static final String LIMIT_SCRIPT = "local key = KEYS[1] "
            + "local limit = tonumber(ARGV[1]) "
            + "local burst = tonumber(ARGV[2]) "
            + "local now = tonumber(ARGV[3]) "
            + "local rate = limit / 1000 "
            + "local last_time = tonumber(redis.call('hget', key, 'last_time') or now) "
            + "local tokens = tonumber(redis.call('hget', key, 'tokens') or burst) "
            + "tokens = math.min(burst, tokens + (now - last_time) * rate) "
            + "if tokens >= 1 then "
            + "    redis.call('hset', key, 'tokens', tokens - 1) "
            + "    redis.call('hset', key, 'last_time', now) "
            + "    return 1 "
            + "else "
            + "    return 0 "
            + "end";

    @Around("@annotation(rateLimit)")
    public Object around(ProceedingJoinPoint point, RateLimit rateLimit) throws Throwable {
        String key = "rate_limit:" + point.getSignature().toShortString();
        List<String> keys = Collections.singletonList(key);
        Object[] args = {rateLimit.limit(), rateLimit.burst(), System.currentTimeMillis()};

        Long result = (Long) redisTemplate.execute(
                new DefaultRedisScript<>(LIMIT_SCRIPT, Long.class), keys, args);

        if (result == 0) {
            throw new BusinessException(429, "Too many requests, please try again later");
        }

        return point.proceed();
    }
}

Technical Challenges and Solutions

The following five technical difficulties are most likely to be probed in interviews, along with production-grade solutions:

Distributed Idempotency Guarantee

Challenges: Concurrent duplicate requests; network timeout retries; business rollback allowing retry.

Optimal solution: Redis deduplication table + unique request ID (recommended). Alternatives: Database unique index; state machine control.

Key points: All write operations must have idempotency; request ID must be generated by frontend; delete Redis key on exception.

Replay Attack Prevention

Challenges: Man-in-the-middle captures and resends requests; signature cracked leading to batch attacks.

Optimal solution: Signature + timestamp + nonce random number. Signature validity 5-15 minutes; nonce stored in Redis for deduplication; critical interfaces add IP whitelist.

Key points: Never use fixed keys; rotate keys periodically; monitor anomalous signature requests.

High Traffic Rate Limiting and Circuit Breaking

Challenges: Burst traffic overwhelms service; downstream failures cause avalanche.

Optimal solution: Redis distributed rate limiting + Sentinel circuit breaking. Rate limiting: token bucket algorithm. Circuit breaking: slow call ratio + exception ratio. Degradation: return default values or cached data.

Key points: Rate limiting thresholds must come from stress testing; circuit breaking must trigger alerts; core endpoints must not degrade.

Sensitive Data Masking

Challenges: Different fields require different masking rules; scattered handling in business code leads to omissions.

Optimal solution: Jackson custom serializer + annotation. Example: @Sensitive(SensitiveType.PHONE) private String phone; Key points: Logs must also be masked; internal interfaces equally need masking; never return full ID numbers.

API Version Compatibility

Challenges: Old versions cannot be taken down immediately; maintaining multiple versions in parallel is costly.

Optimal solution: URL path versioning + canary release. Version numbers as integers (v1, v2); retain old versions 3-6 months; deprecated interfaces get alerts.

Key points: Guarantee backward compatibility within a version; never add features to old versions; monitor old version call volume.

Interview Bonus Points

Canary release : Route traffic to new API version via gateway based on user ID or traffic percentage, reducing release risk.

API Gateway : Push common logic (auth, rate limiting, logging, monitoring) down to gateway layer; business services focus only on core logic.

Real Interview Simulation

The article includes a detailed mock interview covering interface specification, unified response, security (three axes: identity+tamper-proof, replay prevention, transport), idempotency key conflict resolution (prefix with AppKey), version management (never modify in-place, URL versioning, sunset period), traffic spike handling (rate limiting + circuit breaking + idempotency), observability (monitoring + docs + SDK), and long-running task design (async 202 Accepted + polling/webhook).

Core Code & Technical Highlights (Interview Deep-Dive)

① Unified Response Envelope + Global Exception Translation

No hard-coding; use enum for error codes; leverage @RestControllerAdvice to auto-translate exceptions into standard envelopes, avoiding try-catch proliferation.

// Unified response body
@Data
@AllArgsConstructor
public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;
    private String traceId;

    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(200, "success", data, MDC.get("traceId"));
    }

    public static ApiResponse<Void> error(ErrorCode errorCode) {
        return new ApiResponse<>(errorCode.getCode(), errorCode.getMessage(), null, MDC.get("traceId"));
    }
}

// Global exception handler: any uncaught exception becomes standard format
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BizException.class)
    public ApiResponse<Void> handleBizException(BizException e) {
        return ApiResponse.error(e.getErrorCode());
    }

    @ExceptionHandler(Exception.class)
    public ApiResponse<Void> handleException(Exception e) {
        log.error("System exception", e);
        return ApiResponse.error(ErrorCode.SYSTEM_ERROR);
    }
}

Highlight: Uses MDC to propagate traceId, automatically included in response; combined with logging system, not a single trace is lost.

② Signature Verification Interceptor (HMAC-SHA256 + Anti-Replay)

Security core extracted as independent interceptor, non-invasive to business code.

@Component
public class SignatureInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String appKey = request.getHeader("X-AppKey");
        String timestamp = request.getHeader("X-Timestamp");
        String nonce = request.getHeader("X-Nonce");
        String clientSign = request.getHeader("X-Sign");

        // 1. Timestamp offset validation (5-minute window)
        if (Math.abs(System.currentTimeMillis() - Long.parseLong(timestamp)) > 300_000) {
            throw new BizException(ErrorCode.TIMESTAMP_EXPIRED);
        }

        // 2. Nonce anti-replay: Redis setnx atomic exclusion
        String nonceKey = "nonce:" + appKey + ":" + nonce;
        Boolean locked = redisTemplate.opsForValue().setIfAbsent(nonceKey, "1", 5, TimeUnit.MINUTES);
        if (Boolean.FALSE.equals(locked)) {
            throw new BizException(ErrorCode.REPLAY_ATTACK);
        }

        // 3. Recompute signature (params + body)
        String body = getRequestBody(request); // Cached body wrapper
        String sign = HmacUtils.hmacSha256Hex(appSecretMap.get(appKey),
                appKey + timestamp + nonce + body);
        if (!sign.equals(clientSign)) {
            throw new BizException(ErrorCode.SIGN_INVALID);
        }
        return true;
    }
}

Highlight: setIfAbsent provides native atomicity, both anti-replay and lock-free; signature material includes body, preventing request body tampering.

③ Idempotency Annotation + AOP (Aspect Auto-Handling)

Declarative annotation lets business developers add just @Idempotent.

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
    String keyPrefix() default ""; // Business prefix
    long lockTime() default 15;    // Result cache days
}

@Aspect
@Component
public class IdempotentAspect {

    @Around("@annotation(idempotent)")
    public Object around(ProceedingJoinPoint point, Idempotent idempotent) throws Throwable {
        HttpServletRequest request = ((ServletRequestAttributes) Objects.requireNonNull(
                RequestContextHolder.getRequestAttributes())).getRequest();
        String idempotentKey = request.getHeader("Idempotent-Key");
        if (StringUtils.isBlank(idempotentKey)) {
            throw new BizException(ErrorCode.MISSING_IDEMPOTENT_KEY);
        }

        String finalKey = request.getHeader("X-AppKey") + ":" + idempotent.keyPrefix() + ":" + idempotentKey;
        String result = redisTemplate.opsForValue().get(finalKey);
        if (result != null) {
            return JSON.parseObject(result, ApiResponse.class); // Return cached response directly
        }

        Object proceed = point.proceed();
        redisTemplate.opsForValue().set(finalKey, JSON.toJSONString(proceed),
                idempotent.lockTime(), TimeUnit.DAYS);
        return proceed;
    }
}

Highlight: AOP zero-intrusion; caches full response object, truly "first time does the work, subsequent calls return instantly"; key auto-injects tenant prefix for isolation and safety.

Technical Difficulties & Solutions

External APIs are not "good enough if they work"; these hard bones must be cracked or you'll be firefighting daily.

High-Concurrency Idempotency : Risk: Network retries cause duplicate charges/orders. Solution: Redis atomic SETNX + result caching. Key: Mandatory Idempotent-Key with tenant prefix to prevent collisions.

Anti-Replay & Anti-Tampering : Risk: Attackers capture and replay packets; data modified. Solution: HMAC signature + time window + nonce one-time token. Key: Signature includes request body; 5-minute window; nonce stored in Redis.

Seamless Version Upgrade : Risk: Deprecating old endpoints paralyzes callers. Solution: URL path versioning + sunset period. Key: v1/v2 coexist; retain at least one quarter; advance email notification.

Traffic Spike Avalanche : Risk: Double Eleven traffic crushes downstream; cascading failures. Solution: Gateway token bucket rate limiting + business circuit breaking. Key: Exceed threshold returns 429; alerting; degradation returns fallback data.

Long-Running Task Blocking Connections : Risk: Export reports and other long tasks cause HTTP timeouts. Solution: Async: 202 Accepted + polling/webhook. Key: Immediate taskId return; background processing; support callback URL for active notification.

Caller Integration Pain : Risk: Complex signature, idempotency, retry logic leads to abandonment. Solution: Multi-language SDK encapsulation + interactive online docs. Key: OpenAPI-generated docs; SDK completes full call in 10 lines.

Troubleshooting Difficulty : Risk: Cross-system call chains break; blame-shifting wastes time. Solution: Full-chain traceId + unified error code dictionary. Key: Gateway injects traceId; all responses and logs carry it; Grafana correlates.

Finally, a Defense System Panorama diagram ties the core lines of defense together, each layer protecting the systems behind it.

Defense system panorama
Defense system panorama

The interview concludes with the interviewer acknowledging the practical, battle-tested experience demonstrated from code to systemic difficulty analysis.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

API VersioningSpring BootIdempotencyinterview preparationrate limitingAPI SecurityRESTful APICircuit Breaking
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.