Modern API Paradigms

When building the bridge between the React frontend and the Cloud backend, you must choose an API paradigm. Each solves a specific problem.

1. REST (Representational State Transfer)

The traditional workhorse of the web. It uses standard HTTP methods (GET, POST, PUT, DELETE) to interact with "Resources" (URLs).

• Pros: Universally understood, simple, heavily cacheable via HTTP.
• Cons (Overfetching/Underfetching): If the React UI needs a defect's name and the camera's location, a GET /api/defects/1 might return 50 irrelevant fields (overfetching), and you might have to make a separate GET /api/cameras/5 to get the location (underfetching).

Example (Node.js Express & Fetch):

// Server Route
app.get('/api/defects/:id', (req, res) => {
  res.json({ id: 1, type: "scratch", severity: "high", camera_id: 5, timestamp: "..." });
});

// React Client
const response = await fetch('/api/defects/1');
const defect = await response.json();

2. GraphQL

Created by Facebook to solve REST's limitations. It exposes a single endpoint (POST /graphql). The client sends a query specifying exactly the fields it wants, and the server returns a graph of that data.

• Pros: Complete flexibility for the frontend. Great for complex dashboards.
• Cons: Hard to cache, extremely heavy to set up on the backend, susceptible to complex nested query performance issues (N+1 problem).

Example (React Apollo Client): Instead of hitting multiple REST URLs, the frontend sends exactly what it wants:

query GetDefectDashboard {
  defect(id: 1) {
    type
    severity
    camera {     # Automatically joins the camera data in one request!
      location
    }
  }
}

3. gRPC (Google Remote Procedure Call)

Instead of dealing with URLs and JSON, gRPC uses HTTP/2 and Protocol Buffers. A Python script calls visionClient.analyzeFrame(), and under the hood, it transparently executes that function on a Node.js server somewhere else.

• Pros: Blazing fast, strict typing (enforced by the .proto schema), supports bi-directional streaming natively.
• Cons: Not natively supported directly in web browsers (requires gRPC-Web proxies).
• Use Case: Microservices. The Edge Device talking to the Cloud Backend.

Example (gRPC Service Definition):

service VisionAI {
  // A Remote Procedure Call that takes a Frame and returns an Analysis
  rpc AnalyzeFrame (CameraFrame) returns (DefectAnalysis) {}
}

Node.js Client Execution:

// It looks exactly like calling a local javascript function!
const result = await visionClient.analyzeFrame({ image_bytes: buffer });
console.log(result.defect_type);

4. tRPC (TypeScript RPC)

A modern paradigm specifically for full-stack TypeScript apps (like a Next.js App Router). It provides end-to-end type safety without a build step or schema definition. If you change a return type on the Node backend, the React frontend instantly shows a red squiggly error. It's effectively magical developer experience for tightly-coupled monorepos.

Example:

// 1. Next.js Server Router
export const appRouter = router({
  getDefect: publicProcedure.query(() => {
    return { type: "scratch", severity: "high" }; // Hovering over this in VS Code shows the type!
  }),
});

// 2. React Client Component
const { data } = trpc.getDefect.useQuery();
console.log(data.type); // Fully type-safe autocomplete works here instantly!

5. WebSockets

• How it works: A persistent, full-duplex TCP connection. The server can push data to the client instantly.
• Use Case: True real-time data. Pushing live telemetry bars, defect alerts, and robot arm coordinates to the React dashboard without the UI having to ask for it.