1 / 12
Sections
Slide 1
A Network Call Is a Different Boundary
What changes when checkout calls inventory across a network?
- Separate memory requires serialization.
- Independent processes can fail or deploy separately.
- A missing response leaves the caller uncertain.
Slide 2
Follow a REST Request
The response combines transport behavior, HTTP semantics, and a business result.
- Identify a resource with a URI and apply HTTP method semantics.
- Stateless requests carry the context needed to process them.
- JSON is a representation choice, not the definition of REST.
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.
Slide 3
Contracts Survive Independent Deployments
Checkout v1 must keep working when inventory deploys v2. Their contract is the agreement both versions still honor.
- Before: GET /v1/items/sku-123 → 200 {"item_id":"sku-123","available":7}.
- Compatible example: add an optional warehouse field; keep available as an integer. Old clients must tolerate unknown fields.
- Breaking example: rename available to stock, return "seven", or require a new request field. Checkout v1 no longer understands the API.
- Behavior matters too: available means units left after reservations, not total warehouse stock. Preserve that meaning across releases.
Slide 4
Location Is Not Identity
Checkout needs to read inventory. Finding its address is only the first step.
- Example: checkout may read stock; the same identity still needs a separate permission to reserve it.
%%{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.
Slide 5
Spend the Remaining Time Budget
An 800 ms budget with 100 ms already spent and 100 ms reserved leaves at most 600 ms for a dependency.
- Connect timeout bounds connection establishment.
- Read timeout bounds waiting for incoming data, depending on the library.
- A deadline bounds the overall operation.
- Queueing and tail latency matter even when average latency looks good.
Slide 6
Design a Reservation Contract
A shopper wants two units of sku-123. Turn that business action into a contract another team can implement.
- Avoid GET /buy?item=sku-123: a read method should not reserve stock, and the requested quantity is missing.
- Propose POST /v1/reservations with JSON {"item_id":"sku-123","quantity":2} and a verified caller allowed to reserve.
- Success: 201 with reservation_id and quantity. Unknown item: 404. Only one unit left: 409. Invalid quantity: 400.
- Pair challenge: the reservation is saved but its response is lost. How can checkout discover the result without reserving twice?
Slide 7
REST Lab — curl or Postman
Use either curl in a terminal or the Postman desktop app to send the same HTTP requests. Both are accepted for this exercise.
- Run inventory.py and checkout.py in two terminals; keep both running whichever client you choose.
- Send GET http://127.0.0.1:5000/v1/availability/sku-123 with no body and no authentication for this local lab.
- curl: use the supplied commands. Postman: choose GET, paste the URL, and click Send.
- Record status, JSON body, X-Request-ID, and elapsed time. Match that ID in both service logs.
Slide 8
Break
Pause and leave both terminals available for the failure exercise.
- Resume by predicting the result of a two-second dependency delay.
Slide 9
A Timeout Leaves an Unknown Outcome
Inject delay, stop inventory, then restore it and collect evidence.
- Compare 504 timeout with 503 dependency unavailable.
- Confirm checkout health still responds.
- Restore inventory and demonstrate recovery.
- A lost response to a write requires reconciliation or deduplication before retry.
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.
Slide 10
The Same Operation in gRPC
GetItem asks the same inventory question through generated, typed code.
- Typed calls still cross a network: handle NOT_FOUND, UNAVAILABLE, and DEADLINE_EXCEEDED.
%%{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.
Slide 11
Agents Are API Clients Too
A shopping agent is asked to reserve two units. Its tool calls need the same contracts, identity checks, and failure reasoning as checkout.
- Read example: get_inventory("sku-123") returns 200 with available 0. The call succeeded; the agent must report out of stock.
- Write example: reserve("sku-123", 2) times out. The reservation may exist; look up the operation or reuse a supported idempotency key before retrying.
- Permission example: an inventory.read credential cannot reserve stock. The tool service enforces authorization even if the model asks it to proceed.
- Evidence example: attach one request ID to the tool call and service logs so a human can reconstruct what happened.
Slide 12
Explain Your Boundary
Describe a project API using its contract, identity, latency budget, and failure behavior.
- Share a problem statement, team intent, and initial business workflow.
- Identify one synchronous call and sketch its contract.
- Explain why a transport success may still be a business failure.
- Use Canvas for official checkpoint instructions and submissions.