Best Practices for Service Design and API Development in Enterprise Systems

System Overview

JD Enterprise Business VOP (Intelligent Procurement) provides supply‑chain capabilities via APIs; VOP offers hundreds of standard API services that enable thousands of customers to build self‑procurement malls.

Service Path and Modules

Use a unified first‑level path such as domain/api/ to centralize security controls (authentication, authorization, logging, rate‑limiting, monitoring).

Follow with business grouping, e.g., order/api/order or product/api/product , to clarify module ownership.

Consider service granularity (e.g., separate price service vs. embedded in product details) to maintain scenario completeness while offering flexible composition.

Service Request Methods

Most services should support AJAX requests with a fixed data format (JSON/XML) for extensibility; special cases like checkout or login may require non‑AJAX redirects.

Input/Output Parameters

Design parameters with extensibility in mind to avoid breaking changes; use Long or String for numeric fields to prevent overflow.

Distinguish between "unset" and zero values by using wrapper types.

Expose only necessary output fields; sensitive data (address, phone) must be masked or encrypted.

Provide detailed field definitions, length limits, ranges, consistent naming across domains, format specifications, and enum descriptions.

Business Logic Recommendations

Support batch processing to reduce client‑side complexity and server load.

Implement horizontal permission checks to prevent unauthorized data access.

Use dedicated thread pools for critical multi‑threaded tasks.

Exception Handling

Define clear error codes for write operations to enable automated retry, alerting, or graceful degradation.

Wrap unknown exceptions (e.g., NPE, timeout) in a unified response via a global interceptor.

Service Dependencies

Classify external dependencies as strong (must short‑circuit on failure) or weak (can be ignored with alerts) to maintain overall stability.

Monitoring and Logging

Log request and response payloads, especially for financial, order, and payment services, to aid risk assessment and business analytics.

Collect call metrics (frequency, patterns) for traffic governance and security enforcement.

Degradation Points

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

Handling Deprecated Services

Route compatible legacy services to new implementations.

Deprecate by intercepting paths and returning standardized error codes, allowing controlled shutdown.

Trust Boundaries

Never trust third‑party services or callers; enforce rate limiting, input validation, and fine‑grained permission controls.

Security Measures

Use HTTPS for transport encryption.

Apply digital signatures to verify data integrity.

Employ MACs, API keys, and timestamps to prevent replay attacks.

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

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

Interface Tamper‑Proof

Enforce HTTPS.

Use digital signatures and MACs.

Combine API keys with timestamps to mitigate replay attacks.

Input/Output Decryption

For clients requiring end‑to‑end encryption, load customer‑specific encryption SDKs in an isolated platform and apply decryption before business logic and encryption before response.

@Service
public class EncryptInterceptor extends HandlerInterceptorAdapter {
    // Request entry: decrypt before business processing
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        if (!(request instanceof DecryptionRequestWrapper)) {
            return true;
        }
        // Retrieve client authorization and decrypt parameters
        try {
            // Decrypt logic here
            return true;
        } catch (Throwable throwable) {
            // Exception handling
        }
        return true;
    }

    // Response exit: encrypt before sending back
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {
        // Retrieve client identity and encrypt response
        try {
            // Encryption logic here
        } catch (Throwable throwable) {
            // Exception handling
        }
    }
}

Conclusion

Building a robust service architecture requires going beyond standard design guidelines to address security, scalability, extensibility, and graceful degradation, ensuring enterprises can meet evolving business demands and maintain a competitive edge.