REST versus remote procedure calls

01Style, protocol, and encoding are separate

A customer wants to reserve seat A12 for a show. The API can present that action in two styles:

• Resource-oriented: create a reservation through POST /reservations, then read its saved state at GET /reservations/42.
• Named operation: call ReserveSeat(show, seat) and later GetReservation(42). This is remote procedure call, or RPC: a client invokes a named operation elsewhere.

REST is broader than resource-shaped URLs. It requires a consistent interface, separate client/server roles, stateless requests, explicit caching rules and support for intermediary layers. Reading a reservation must not secretly create another seat claim.

Keep style, transport and data encoding separate. HTTP describes requests and responses. JSON writes values as text; Protocol Buffers is a binary encoding. RPC can use HTTP and JSON too. gRPC is one RPC framework, not all RPC. Either style still needs permissions, compatibility, deadlines and safe retry behavior.

02Design effects before endpoint names

Specify the seat operation before choosing names:

Then define effects

1. A read returns state without creating another reservation. This preserves the meaning of a GET.
2. A repeated defined DELETE asks for the same removal effect. The first response and a later “already absent” response may differ.
3. A create needs explicit retry handling. Neither POST spelling nor an RPC function name automatically remembers the earlier result.
4. State required fields and errors. Distinguish invalid input, a known unavailable seat and an unknown result after timeout.

An operation is idempotent when repeating it has the same intended effect as applying it once. Responses need not be identical and the server may still log attempts. A create or charge commonly needs a request key plus a saved outcome to obtain that behavior.

For ordinary public reads, HTTP caching and version validators can help. Internal operation-heavy services may benefit from generated request types or two-way streams. These tools do not replace the effect rules.

03Worked example: reservation timeout

The customer supplies request key K7 for one attempt to reserve A12. Follow a lost response:

1. The service authenticates the caller and checks the request. The service looks up K7 together with the verified account and the reservation-create operation. Another account’s K7, or a payment operation with that text, is not this request.
2. The database saves the reservation and K7's outcome together. It also retains enough original request content to detect a changed seat under the same key. A unique account/operation/request-key constraint prevents two concurrent K7 attempts creating separate outcomes. A transaction commits the required records together or not at all; a losing concurrent attempt reads the committed result.
3. The reply is lost. The client does not know whether A12 was reserved. Timeout is not proof that the transaction rolled back.
4. The client retries K7 with A12 again. The service looks up K7, verifies matching content and returns its saved reservation result. It does not allocate another seat.
5. The client accidentally uses K7 for B14. Reject that mismatch. A different requested seat is a new intent, not a matching retry.

This sequence works for either interface style.

Also preserve a caller deadline. If 120 ms has elapsed out of 300 ms, a downstream call has at most 180 ms left, including the return path. Cancellation can stop more work, but cannot undo a reservation already committed.

A binary representation may reduce bytes without much response-time improvement when storage, queue waiting or distance dominates. Compare equivalent complete operations rather than choosing a winner from format alone.

04Explain a contract a client can depend on

Make the choice reviewable:

• Resource collections and predictable read behavior can suit broad public APIs.
• Explicit commands and generated request types can suit operation-heavy internal workflows.
• Old clients still exist. Define behavior for omitted new fields and unknown enum values. Code generation does not update deployed mobile applications.
• Show one request and result. Name its success identity, business rejection, uncertain timeout, request key and deadline.
• Document read caching and command repetition separately. State which account and operation share a retry key, rather than assuming one global key space.

Neither style is inherently faster, safer or more scalable. Explain what a caller does after uncertainty, and show the saved records that make that behavior possible.