Service Design Tips and Security Practices for Robust API Development

System Introduction

JD Enterprise Business VOP (Intelligent Procurement) provides hundreds of standard API services to thousands of customers, enabling the construction of self‑procurement malls.

Service Path and Modules

Use a unified top‑level path (e.g., domain/api/ ) to simplify security controls such as authentication, authorization, logging, rate‑limiting, and monitoring.

Organize business groups (e.g., order/api/order , product/api/product ) for clear module identification.

Consider service granularity—decide whether to expose price as a separate service or embed it in product details, based on business scenarios.

Service Request Methods

Support AJAX requests with fixed data formats (JSON/XML) for most services; use non‑AJAX requests for special cases like checkout or login where server‑side forwarding is required.

Service Input/Output Parameters

Prioritize extensibility; use Long or String for numeric fields to avoid future overflow issues.

Distinguish between “unset” and zero values by using wrapper types.

Expose only necessary output fields; apply masking or encryption for sensitive data such as addresses and phone numbers.

Provide detailed field definitions, length limits, ranges, consistent naming, format specifications, and enum explanations.

Handling Published Services

When adding new fields to already released services, consider the impact on callers’ serialization/deserialization; use strict mode handling and optional extension fields to maintain compatibility.

Business Processing Recommendations

Support batch processing to reduce high‑concurrency pressure on services.

Implement horizontal permission checks to prevent unauthorized data access.

Use dedicated thread pools for critical business logic to avoid resource contention.

Exception Handling

Define clear error codes for write‑operations; ensure callers can programmatically handle retries, alerts, or ignore failures based on standardized error information.

Strong and Weak Dependencies

Classify external calls as strong (must short‑circuit on failure) or weak (allow continuation with alerts) to maintain overall system stability.

Monitoring and Logging

Record request/response logs for critical services (funds, orders, payments) to aid risk assessment and business analysis.

Collect call metrics to detect abnormal usage patterns and support rate‑limiting and security measures.

Reasonable Degradation Points

Identify critical and non‑critical modules; embed degradation logic in non‑critical code to preserve core service availability during failures.

Handling Obsolete Services

Route compatible old services to new implementations.

Deprecate by intercepting paths and returning unified error codes, allowing controlled rollback after monitoring.

Sensitive Fields

Encrypt sensitive B2B data (phone, name, address) at transport, application, or database layers using standard algorithms (AES, RSA) and manage keys securely.

System Admission

Use IP white‑list/black‑list mechanisms to restrict access for high‑security customers.

Interface Tamper‑Proofing

Enforce HTTPS for encrypted transport.

Apply digital signatures to verify data integrity.

Use MACs with shared keys for message authentication.

Combine API keys with timestamps to prevent replay attacks.

Input/Output Encryption and Decryption

Implement request‑side decryption and response‑side encryption via interceptors, supporting per‑customer SDKs for flexible encryption strategies.

{
"success": true,
"resultMessage": "success",
"resultCode": "0000",
"result": {}
}

Code Example: Encryption Interceptor

/**
* @description 指定客户接口出入参加解密拦截器
*/
@Service
public class EncryptInterceptor extends HandlerInterceptorAdapter {
// 请求进入，业务处理前解密
@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
if (!(request instanceof DecryptionRequestWrapper)) {
return true;
}
// 获取客户授权信息，获取当前客户身份
try {
// 判断该客户是否开启接口加解密
// 组织参数，获取原始入参，进行解密操作
// 解密完成后，将解密得到的参数全部加入到 request 的参数内
// 继续向下进行
return true;
} catch (Throwable throwable) {
// 异常处理
}
}
// 返回前加密
@Override
public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
// 获取客户身份标识
try {
// 判断该客户是否开启接口加解密
// 调用原始的 postHandle 方法，让响应数据被写入包装类的输出流
// 调用加密方法，获取加密后数据
// 将加密后的数据写回响应
} catch (Throwable throwable) {
// 异常处理
}
}
}

Conclusion

Building robust services requires adhering to design standards while also addressing security, scalability, extensibility, and graceful degradation to meet evolving business demands.