CMPE273 · Module 3

Network Communication with REST and gRPC

Design explicit API contracts, distinguish service location from identity, budget network latency, and observe how REST and gRPC calls behave under failure.

Learning Objectives

  1. Design a resource-oriented HTTP API with explicit success and error contracts.
  2. Explain serialization and compatible contract evolution across independent deployments.
  3. Distinguish service discovery, authentication, authorization, and correlation IDs.
  4. Allocate a latency budget and distinguish connect timeouts, read timeouts, and deadlines.
  5. Demonstrate success, slow responses, and dependency failure using two services.
  6. Compare REST with typed gRPC calls and justify a protocol choice.

Core Concepts

API Contract

Agreement covering operations, schemas, errors, identity requirements, and behavioral semantics.

Serialization

Encoding in-memory values into transferable bytes and decoding them at the receiver.

Service Identity

An authenticated principal representing a workload; a DNS name or caller-supplied label alone is not proof of identity.

Latency Budget

The time available for a complete operation, shared by local work and downstream calls.

Timeout and Deadline

A timeout bounds a particular wait; a deadline marks when the whole operation must stop waiting.

Typed RPC

A remote operation described by a service interface and message types, often with generated client and server code.

Diagrams

Inventory lookup across a network

sequenceDiagram
  participant C as Checkout client
  participant I as Inventory service
  participant D as Inventory data
  C->>I: GET /v1/items/sku-123
  I->>I: Authenticate and validate
  I->>D: Read item
  D-->>I: Available quantity
  I-->>C: 200 and JSON representation

Checkout serializes an HTTP request to inventory, which validates the request and reads its data. The response returns status, headers, and a JSON representation. Network and queue time add to application execution time.

Four checks before inventory returns stock

%%{init: {"themeVariables": {"fontSize": "24px"}, "flowchart": {"wrappingWidth": 400, "nodeSpacing": 50, "rankSpacing": 12, "padding": 10}}}%%
flowchart TB
  subgraph locate[Connect to the right server]
    direction LR
    D["1. Find inventory<br/>Resolve its address"] --> T["2. Verify server<br/>Check TLS certificate"]
  end
  subgraph trust[Server checks the caller]
    direction LR
    A["3. Verify caller token<br/>Identity is checkout"] --> P["4. Check permission<br/>Allow inventory.read"]
  end
  locate --> trust

A verified checkout token with inventory.read permits the lookup. A caller who only sends X-Service-Name checkout has not proved its identity and must not gain access.

Caller stops waiting before the server finishes

sequenceDiagram
  participant U as User
  participant C as Checkout
  participant I as Inventory
  U->>C: Get availability
  C->>I: Read item
  Note over I: Injected delay of 2 seconds
  Note over C: Read timeout after 0.6 seconds
  C-->>U: 504 dependency_timeout
  I-->>C: Late response, caller no longer waiting

Checkout sends a request but its read timeout expires before inventory finishes. Checkout returns a controlled gateway timeout. Inventory can still finish later; the client timeout has not cancelled or rolled back the server operation.

Define once, generate bindings, then call remotely

%%{init: {"themeVariables": {"fontSize": "24px"}, "flowchart": {"wrappingWidth": 400, "nodeSpacing": 50, "rankSpacing": 12, "padding": 10}}}%%
flowchart TB
  subgraph build[Build time]
    direction LR
    P["inventory.proto<br/>Define GetItem types"] --> G["Generate bindings<br/>Client + server code"]
  end
  subgraph runtime[Runtime]
    direction LR
    C["Checkout client<br/>GetItem sku-123"] -->|HTTP/2 + Protobuf| I["Inventory server<br/>Return available 7"]
  end
  build --> runtime

A proto defines GetItem and its messages. Generated bindings support both sides. At runtime the client sends item_id sku-123 and receives available 7; a deadline still bounds its wait.

Key Takeaways

Lab Links