When to choose a REST API over Kafka and vice versa

package com.bank.service;

import org.springframework.web.client.RestClient;
import java.math.BigDecimal;

public class BalanceQueryService {

    private final RestClient restClient;

    public BalanceQueryService(RestClient.Builder builder) {
        this.restClient = builder.baseUrl("http://account-service").build();
    }

    public BigDecimal getBalance(String accountId) {
        // REST is correct here: caller needs the balance NOW
        return restClient.get()
                .uri("/api/v1/accounts/{id}/balance", accountId)
                .retrieve()
                .body(BigDecimal.class);
    }
}

package com.bank.service;

import com.bank.event.TransferCompletedEvent;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.stereotype.Service;
import java.math.BigDecimal;

@Service
public class TransferEventPublisher {

    private final KafkaTemplate<String, TransferCompletedEvent> kafkaTemplate;

    public TransferEventPublisher(
            KafkaTemplate<String, TransferCompletedEvent> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    public void publishTransferCompleted(String accountId, BigDecimal amount) {
        TransferCompletedEvent event = new TransferCompletedEvent(
                accountId, amount, "INR");
        // Kafka is correct here: fire and forget, many consumers react
        kafkaTemplate.send("transfer-events", accountId, event);
    }
}

// Producer returns in ~2ms
// Consumer group 1 (Notification): sends SMS to Priya
// Consumer group 2 (Statement): appends to monthly statement
// Consumer group 3 (Fraud): scores the transaction
// Consumer group 4 (Analytics): updates the dashboard

// WRONG: REST fan-out couples the transfer to five services
public void completeTransfer(String accountId, BigDecimal amount) {
    notificationClient.sendSms(accountId, amount);    // blocks
    statementClient.appendEntry(accountId, amount);    // blocks
    fraudClient.scoreTransaction(accountId, amount);   // blocks
    analyticsClient.recordTransfer(accountId, amount); // blocks
    auditClient.logTransfer(accountId, amount);        // blocks
    // If ANY of these is down, the transfer fails or hangs
}

package com.bank.consumer;

import com.bank.event.TransferCompletedEvent;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
public class NotificationConsumer {

    private final NotificationRepository notificationRepo;

    public NotificationConsumer(NotificationRepository notificationRepo) {
        this.notificationRepo = notificationRepo;
    }

    @KafkaListener(topics = "transfer-events", groupId = "notification-svc")
    public void onTransferCompleted(TransferCompletedEvent event) {
        // Idempotent: check if we already sent this notification
        if (notificationRepo.existsByEventId(event.eventId())) {
            return; // Already processed, skip duplicate
        }
        sendSms(event.accountId(), event.amount());
        notificationRepo.markProcessed(event.eventId());
    }

    private void sendSms(String accountId, java.math.BigDecimal amount) {
        // Send SMS to account holder
    }
}

package com.bank.service;

import com.bank.client.AccountClient;
import com.bank.event.TransferCompletedEvent;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.stereotype.Service;
import java.math.BigDecimal;

@Service
public class TransferService {

    private final AccountClient accountClient;
    private final KafkaTemplate<String, TransferCompletedEvent> kafkaTemplate;

    public TransferService(AccountClient accountClient,
                            KafkaTemplate<String, TransferCompletedEvent> kafka) {
        this.accountClient = accountClient;
        this.kafkaTemplate = kafka;
    }

    public String transfer(String from, String to, BigDecimal amount) {
        // REST: synchronous, caller needs the answer
        BigDecimal balance = accountClient.getBalance(from);
        if (balance.compareTo(amount) < 0) {
            throw new InsufficientFundsException("Balance: " + balance);
        }
        accountClient.debit(from, amount);
        accountClient.credit(to, amount);

        // Kafka: asynchronous, side effects happen independently
        String txnId = "TXN-" + System.currentTimeMillis();
        kafkaTemplate.send("transfer-events", from,
                new TransferCompletedEvent(txnId, from, to, amount));

        return txnId;
    }
}

// WRONG: publishing to Kafka and then polling for a reply topic
// This is forcing synchronous semantics onto an async system
kafkaTemplate.send("balance-request", accountId, request);
// Now poll "balance-response" topic waiting for the reply...
// This is slow, fragile, and misuses Kafka

// CORRECT: REST for immediate answers
BigDecimal balance = restClient.get()
        .uri("/api/v1/accounts/{id}/balance", accountId)
        .retrieve()
        .body(BigDecimal.class);

// Key by accountId so all events for SAV2001 land on the same partition
kafkaTemplate.send("transfer-events", "SAV2001", event);
// This guarantees: debit event for SAV2001 is consumed before credit event
// Without a key, events could land on different partitions and arrive out of order