Design Paradigms

Need a simple CRUD API?                    → REST
Need flexible queries for complex UIs?      → GraphQL
Need fast internal service communication?   → gRPC
Need real-time bidirectional data?           → WebSockets

Still unsure? Start with REST.
It's the simplest, most understood, most cacheable option.
Only move to another paradigm when REST's limitations hurt you.

Products:
  GET    /api/products          → List all products
  GET    /api/products/42       → Get product #42
  POST   /api/products          → Create a new product
  PUT    /api/products/42       → Replace product #42 entirely
  PATCH  /api/products/42       → Update specific fields of product #42
  DELETE /api/products/42       → Delete product #42

Orders:
  GET    /api/users/7/orders    → List orders for user #7
  POST   /api/orders            → Create a new order
  GET    /api/orders/101        → Get order #101
  PATCH  /api/orders/101        → Update order #101 (e.g., cancel)

Nested Resources:
  GET    /api/orders/101/items  → List items in order #101

REST approach (3 requests):
  GET /api/users/42           → { id, name, email, avatar, bio, ... }
  GET /api/users/42/orders    → [{ id, total, status, items, ... }, ...]
  GET /api/orders/101/reviews → [{ id, rating, comment, ... }, ...]

GraphQL approach (1 request):
  POST /graphql
  {
    user(id: 42) {
      name
      email
      orders(last: 5) {
        id
        total
        reviews {
          rating
        }
      }
    }
  }

Response — exactly what was asked:
  {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "orders": [
        {
          "id": "101",
          "total": 59.99,
          "reviews": [{ "rating": 5 }]
        }
      ]
    }
  }

syntax = "proto3";

package user;

// The data structure
message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
  repeated Order orders = 4;
}

message Order {
  int32 id = 1;
  double total = 2;
  string status = 3;
}

// The service definition
service UserService {
  // Unary — one request, one response
  rpc GetUser(GetUserRequest) returns (User);

  // Server streaming — one request, stream of responses
  rpc ListOrders(ListOrdersRequest) returns (stream Order);

  // Client streaming — stream of requests, one response
  rpc UploadLogs(stream LogEntry) returns (UploadResult);

  // Bidirectional streaming — both sides stream
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message GetUserRequest { int32 id = 1; }
message ListOrdersRequest { int32 user_id = 1; }
message LogEntry { string message = 1; int64 timestamp = 2; }
message UploadResult { int32 count = 1; }
message ChatMessage { string text = 1; string sender = 2; }