api-integration（API 集成）

API Integration Skill

Purpose

Provide robust patterns for integrating the CIA platform with external government data APIs, including the Swedish Riksdagen, Election Authority, World Bank, and ESV (Swedish Financial Management Authority). Covers resilience, caching, and error handling.

When to Use

• ✅ Integrating new external data sources
• ✅ Improving reliability of existing API connections
• ✅ Implementing caching for frequently accessed political data
• ✅ Adding rate limiting to respect API provider constraints
• ✅ Debugging API integration failures

Do NOT use for:

• ❌ Internal service-to-service calls (use Spring patterns directly)
• ❌ Database access patterns (use JPA/Hibernate skill)

CIA External API Landscape

Retry Logic Pattern

Exponential Backoff with Jitter

@Service
public class ResilientApiClient {

    private static final int MAX_RETRIES = 3;
    private static final long BASE_DELAY_MS = 1000;
    private static final Logger LOG = LoggerFactory.getLogger(ResilientApiClient.class);

    public <T> T executeWithRetry(Supplier<T> apiCall, String operationName) {
        int attempt = 0;
        while (true) {
            try {
                return apiCall.get();
            } catch (Exception e) {
                attempt++;
                if (attempt >= MAX_RETRIES || !isRetryable(e)) {
                    LOG.error("API call failed after {} attempts: {}", attempt, operationName, e);
                    throw new ApiIntegrationException(operationName, e);
                }
                long delay = calculateBackoff(attempt);
                LOG.warn("Retry {}/{} for {} after {}ms", attempt, MAX_RETRIES, operationName, delay);
                try {
                    Thread.sleep(delay);
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    throw new ApiIntegrationException(operationName, ie);
                }
            }
        }
    }

    private long calculateBackoff(int attempt) {
        long exponentialDelay = BASE_DELAY_MS * (1L << (attempt - 1));
        long jitter = ThreadLocalRandom.current().nextLong(0, exponentialDelay / 2);
        return Math.min(exponentialDelay + jitter, 30_000);
    }

    private boolean isRetryable(Exception e) {
        if (e instanceof HttpClientErrorException httpErr) {
            int status = httpErr.getStatusCode().value();
            return status == 429 || status >= 500;
        }
        return e instanceof ResourceAccessException
            || e instanceof SocketTimeoutException;
    }
}

Circuit Breaker Pattern

@Component
public class CircuitBreaker {

    private enum State { CLOSED, OPEN, HALF_OPEN }

    private State state = State.CLOSED;
    private int failureCount = 0;
    private long lastFailureTime = 0;

    private static final int FAILURE_THRESHOLD = 5;
    private static final long RECOVERY_TIMEOUT_MS = 60_000;

    public synchronized <T> T execute(Supplier<T> action, Supplier<T> fallback) {
        if (state == State.OPEN) {
            if (System.currentTimeMillis() - lastFailureTime > RECOVERY_TIMEOUT_MS) {
                state = State.HALF_OPEN;
            } else {
                return fallback.get();
            }
        }

        try {
            T result = action.get();
            reset();
            return result;
        } catch (Exception e) {
            recordFailure();
            return fallback.get();
        }
    }

    private synchronized void recordFailure() {
        failureCount++;
        lastFailureTime = System.currentTimeMillis();
        if (failureCount >= FAILURE_THRESHOLD) {
            state = State.OPEN;
        }
    }

    private synchronized void reset() {
        failureCount = 0;
        state = State.CLOSED;
    }
}

Caching Strategy

Spring Cache Configuration

@Configuration
@EnableCaching
public class ApiCacheConfig {

    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager manager = new CaffeineCacheManager();
        manager.setCaffeine(Caffeine.newBuilder()
            .maximumSize(10_000)
            .expireAfterWrite(Duration.ofHours(1))
            .recordStats());
        return manager;
    }
}

@Service
public class RiksdagDataService {

    @Cacheable(value = "politicians", key = "#personId")
    public PoliticianData getPolitician(String personId) {
        return riksdagClient.fetchPerson(personId);
    }

    @CacheEvict(value = "politicians", allEntries = true)
    @Scheduled(cron = "0 0 2 * * *") // Refresh at 2 AM daily
    public void evictPoliticianCache() {
        LOG.info("Evicting politician cache for daily refresh");
    }
}

Cache TTL Guidelines

Rate Limiting

@Component
public class RateLimiter {

    private final Semaphore semaphore;
    private final ScheduledExecutorService scheduler;

    public RateLimiter(@Value("${api.rate.limit:10}") int maxRequestsPerSecond) {
        this.semaphore = new Semaphore(maxRequestsPerSecond);
        this.scheduler = Executors.newSingleThreadScheduledExecutor();
        this.scheduler.scheduleAtFixedRate(
            () -> semaphore.release(maxRequestsPerSecond - semaphore.availablePermits()),
            1, 1, TimeUnit.SECONDS
        );
    }

    public <T> T throttled(Supplier<T> apiCall) throws InterruptedException {
        semaphore.acquire();
        return apiCall.get();
    }
}

Error Handling

public class ApiIntegrationException extends RuntimeException {
    private final String operationName;
    private final int httpStatus;

    public ApiIntegrationException(String operationName, Throwable cause) {
        super("API integration failed: " + operationName, cause);
        this.operationName = operationName;
        this.httpStatus = extractStatus(cause);
    }
}

Security Considerations

• Never log API keys or tokens — mask sensitive headers in logs
• Validate all API responses — treat external data as untrusted input
• Use HTTPS exclusively — reject insecure connections
• Timeout connections — set connect (5s) and read (30s) timeouts
• Sanitize data — escape or validate all data before database storage

ISMS Alignment