# REST — The Foundation
REST (Representational State Transfer) uses HTTP verbs with resource-based URLs. It's the lingua franca of web APIs.
GET /v1/users → List users (Safe, Idempotent) GET /v1/users/42 → Get user 42 (Safe, Idempotent) POST /v1/users → Create user (NOT Idempotent) PUT /v1/users/42 → Replace user 42 (Idempotent) PATCH /v1/users/42 → Update fields (Idempotent*) DELETE /v1/users/42 → Delete user 42 (Idempotent) Status Codes: 200 OK │ 201 Created │ 204 No Content 400 Bad Req │ 401 Unauth │ 403 Forbidden 404 Not Found │ 409 Conflict │ 429 Rate Limited 500 Server Err│ 502 Bad GW │ 503 Unavailable
# gRPC — High-Performance RPC
gRPC uses Protocol Buffers for serialization and HTTP/2 for transport. It's ideal for microservice-to-microservice communication where performance matters.
// user.proto — schema definition
syntax = "proto3";
service UserService {
rpc GetUser (GetUserRequest) returns (User);
rpc ListUsers (ListRequest) returns (stream User); // server streaming
}
message GetUserRequest {
int64 id = 1;
}
message User {
int64 id = 1;
string name = 2;
string email = 3;
}When to use: Internal services, polyglot environments (auto-generated clients), when latency matters, streaming data. When NOT to use: Public APIs consumed by browsers (limited browser support), simple CRUD where REST suffices.
# GraphQL — Client-Driven Queries
GraphQL lets clients request exactly what they need. Single endpoint, typed schema, introspection.
# Client requests only the fields it needs
query {
user(id: 42) {
name
posts(first: 5) {
title
commentCount
}
}
}
# One request, exact data. No over-fetching.
# Compare REST: GET /users/42 + GET /users/42/posts# Rate Limiting & Versioning
Rate limiting protects your API from abuse. Versioning lets you evolve without breaking clients.
Rate Limit Headers: X-RateLimit-Limit: 100 ← max requests X-RateLimit-Remaining: 42 ← requests left X-RateLimit-Reset: 1625097600 ← when bucket refills Retry-After: 30 ← seconds to wait (on 429) Versioning Strategies: /v1/users ← URL path (most common) Accept: app/v2 ← Content negotiation ?version=2 ← Query parameter API-Version: 2 ← Custom header
⚡ Key Takeaways
- REST for public APIs and simple CRUD — universal, well-understood
- gRPC for internal microservices — fast, type-safe, streaming support
- GraphQL when clients have varied data needs — eliminates over/under-fetching
- Always version your APIs — never break existing clients
- Rate limit everything — use token bucket, return helpful headers
- Design APIs around resources, not actions