gRPC vs REST: When to Use Each in Modern APIs

// ── 1. Define the contract in .proto file ──────────────────────────────────
// File: src/main/proto/payment.proto
/*
syntax = "proto3";
option java_package = "io.thecodeforge.payment.grpc";
option java_outer_classname = "PaymentProto";

service PaymentService {
  // Unary RPC — one request, one response (like REST)
  rpc ProcessPayment(PaymentRequest) returns (PaymentResponse);

  // Server streaming — one request, stream of responses
  rpc StreamTransactions(TransactionFilter) returns (stream Transaction);

  // Client streaming — stream of requests, one response
  rpc BatchPayments(stream PaymentRequest) returns (BatchResult);

  // Bidirectional streaming — both sides stream
  rpc PaymentFeed(stream PaymentEvent) returns (stream PaymentEvent);
}

message PaymentRequest {
  string customer_id = 1;
  int64 amount_pence = 2;
  string currency    = 3;
}

message PaymentResponse {
  string payment_id = 1;
  string status     = 2;
  int64  timestamp  = 3;
}
*/

// ── 2. Generated server implementation ─────────────────────────────────────
package io.thecodeforge.payment.grpc;

import io.grpc.stub.StreamObserver;

public class PaymentServiceImpl
    extends PaymentServiceGrpc.PaymentServiceImplBase {

    @Override
    public void processPayment(
            PaymentRequest request,
            StreamObserver<PaymentResponse> responseObserver) {

        // Business logic
        String paymentId = processInternally(
            request.getCustomerId(),
            request.getAmountPence(),
            request.getCurrency()
        );

        // Build protobuf response (binary, not JSON)
        PaymentResponse response = PaymentResponse.newBuilder()
            .setPaymentId(paymentId)
            .setStatus("COMPLETED")
            .setTimestamp(System.currentTimeMillis())
            .build();

        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }

    private String processInternally(String customerId, long amount, String currency) {
        // Payment processing logic
        return "pay-" + System.nanoTime();
    }
}

// ── 3. Client usage — generated stub handles serialisation ─────────────────
package io.thecodeforge.payment.grpc;

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class PaymentClient {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("payment-service.internal", 50051)
            .usePlaintext()
            .build();

        PaymentServiceGrpc.PaymentServiceBlockingStub stub =
            PaymentServiceGrpc.newBlockingStub(channel);

        PaymentRequest request = PaymentRequest.newBuilder()
            .setCustomerId("customer-42")
            .setAmountPence(10000)  // £100.00
            .setCurrency("GBP")
            .build();

        PaymentResponse response = stub.processPayment(request);
        System.out.println("Payment ID: " + response.getPaymentId());
        System.out.println("Status: "    + response.getStatus());
    }
}

package io.thecodeforge.payment.rest;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/v1/payments")
public class PaymentRestController {

    private final PaymentService paymentService;

    public PaymentRestController(PaymentService paymentService) {
        this.paymentService = paymentService;
    }

    @PostMapping
    public ResponseEntity<PaymentResponse> processPayment(
            @RequestBody PaymentRequest request) {

        // REST: consumed by any HTTP client, browser, curl, Postman
        // No code generation required. Request/response in JSON.
        PaymentResult result = paymentService.process(
            request.getCustomerId(),
            request.getAmountPence(),
            request.getCurrency()
        );

        return ResponseEntity.ok(new PaymentResponse(
            result.getPaymentId(),
            result.getStatus().name(),
            result.getTimestamp()
        ));
    }

    @GetMapping("/{paymentId}")
    public ResponseEntity<PaymentResponse> getPayment(@PathVariable String paymentId) {
        return paymentService.findById(paymentId)
            .map(p -> ResponseEntity.ok(new PaymentResponse(p)))
            .orElse(ResponseEntity.notFound().build());
    }
}

// curl -X POST https://api.thecodeforge.io/v1/payments \
//   -H 'Content-Type: application/json' \
//   -d '{"customerId":"c-42","amountPence":10000,"currency":"GBP"}'
//
// Response:
// {"paymentId":"pay-1234","status":"COMPLETED","timestamp":1711756800000}

package io.thecodeforge.payment.grpc;

import io.grpc.stub.StreamObserver;
import java.util.List;

public class TransactionStreamingServiceImpl
    extends TransactionServiceGrpc.TransactionServiceImplBase {

    private final TransactionRepository transactionRepo;

    public TransactionStreamingServiceImpl(TransactionRepository repo) {
        this.transactionRepo = repo;
    }

    // Server streaming: client sends one filter, server streams matching transactions
    // Useful for: exporting large datasets without pagination loops
    @Override
    public void streamTransactions(
            TransactionFilter filter,
            StreamObserver<Transaction> responseObserver) {

        // Fetch and stream — client receives each transaction as it's sent
        // No need to buffer the entire result set in memory
        transactionRepo.findByCustomerIdAndDateRange(
            filter.getCustomerId(),
            filter.getFromTimestamp(),
            filter.getToTimestamp()
        ).forEach(tx -> {
            Transaction proto = Transaction.newBuilder()
                .setTransactionId(tx.getId())
                .setAmountPence(tx.getAmountPence())
                .setCurrency(tx.getCurrency())
                .setTimestamp(tx.getTimestamp())
                .build();
            responseObserver.onNext(proto);  // Each transaction sent immediately
        });

        responseObserver.onCompleted();
    }

    // Client streaming: client sends batch of payments, server responds once
    @Override
    public StreamObserver<PaymentRequest> batchPayments(
            StreamObserver<BatchResult> responseObserver) {

        return new StreamObserver<>() {
            int processed = 0;
            int failed = 0;

            @Override
            public void onNext(PaymentRequest request) {
                // Process each payment as it arrives from client
                try {
                    processPayment(request);
                    processed++;
                } catch (Exception e) {
                    failed++;
                }
            }

            @Override
            public void onCompleted() {
                // Client done sending — send summary response
                responseObserver.onNext(BatchResult.newBuilder()
                    .setProcessed(processed)
                    .setFailed(failed)
                    .build());
                responseObserver.onCompleted();
            }

            @Override
            public void onError(Throwable t) {
                // Handle client-side error
            }
        };
    }
}