REST & gRPC — Basics

REST & gRPC — Basics

REST (Representational State Transfer)

Architectural style on top of HTTP. Resources identified by URLs, manipulated via HTTP verbs.

Verbs and idempotency

Verb	Purpose	Idempotent	Safe
GET	read	yes	yes
HEAD	read headers	yes	yes
POST	create / arbitrary	no	no
PUT	full replace	yes	no
PATCH	partial update	typically no (depends on impl)	no
DELETE	remove	yes	no
OPTIONS	CORS preflight	yes	yes

Safe = no side effects. Idempotent = same result for repeated calls.

Status codes

• 2xx success: 200 OK, 201 Created, 202 Accepted, 204 No Content.
• 3xx: 301 Moved, 302 Found, 304 Not Modified.
• 4xx client error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable, 429 Too Many Requests.
• 5xx server error: 500, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout.

Conventions

• Resources are nouns: /users/123, not /getUser?id=123.
• Plural collections: /users, /users/123/orders.
• Filter/sort/page via query: ?status=paid&sort=-created_at&limit=20&cursor=....
• Versioning: /v1/... or Accept: application/vnd.acme.v1+json.
• HATEOAS in pure REST — links included in response. Rare in practice.

Pagination

• Offset (?offset=100&limit=50) — simple but slow at scale, unstable on inserts.
• Cursor / keyset — opaque token from previous response. Fast, stable.
• Page (?page=3&size=50) — same problems as offset.

Caching

• Cache-Control, ETag, Last-Modified. Conditional GET with If-None-Match / If-Modified-Since.

gRPC

Google’s RPC framework. Built on HTTP/2 + Protocol Buffers.

Components

• .proto files define services, methods, message types.
• Code generator produces client + server stubs (any language).
• Strongly typed contracts.

syntax = "proto3";
package users.v1;

service Users {
  rpc Get (GetRequest) returns (User);
  rpc List (ListRequest) returns (stream User);
  rpc Watch (stream WatchRequest) returns (stream Event);
}

message User {
  string id    = 1;
  string email = 2;
  int64  created_at = 3;
}

4 RPC types

1. Unary — request/response.
2. Server streaming — one request, stream of responses.
3. Client streaming — stream of requests, one response.
4. Bidirectional streaming — both stream simultaneously.

Why HTTP/2

• Multiplexing — many streams over one TCP connection.
• Header compression (HPACK).
• Binary framing.
• Server push (rarely used in gRPC).
• Solves head-of-line blocking at HTTP layer.

Status codes (gRPC)

• OK, CANCELLED, UNKNOWN, INVALID_ARGUMENT, DEADLINE_EXCEEDED, NOT_FOUND, ALREADY_EXISTS, PERMISSION_DENIED, RESOURCE_EXHAUSTED, FAILED_PRECONDITION, ABORTED, OUT_OF_RANGE, UNIMPLEMENTED, INTERNAL, UNAVAILABLE, DATA_LOSS, UNAUTHENTICATED.

Deadlines (timeouts)

Every RPC carries a deadline that propagates with the call. Server stops work when exceeded.

When to use which

Use case	Pick
Public/partner API consumed by browsers/mobile	REST (or GraphQL)
Service-to-service inside cluster	gRPC
Real-time bidirectional	gRPC streaming or WebSocket
Easy debugging via curl/Postman	REST
High throughput, low latency, polyglot internal	gRPC
Edge / CDN cacheable	REST

OpenAPI (REST)

• YAML/JSON spec describing endpoints. Generates clients, docs, mocks, validators.
• Tools: Swagger UI, Stoplight, Redocly, openapi-generator.

Protocol Buffers

• Binary, schema-evolved (numbered fields, never reuse / renumber).
• Smaller and faster than JSON. Strongly typed.
• Field numbers 1-15: 1 byte; 16-2047: 2 bytes — keep frequent fields low.
• Default values: scalar zero, bool false, string "", repeated empty.
• optional keyword reintroduced in proto3 (3.15+) to distinguish unset from default.