API Design.

REST (Representational State Transfer) is an architectural style for distributed systems, defined by Roy Fielding in 2000. It is a set of constraints, not a protocol or a standard.

Six constraints define the style:

• Client-server: the two sides evolve on their own.
• Stateless: each request carries everything the server needs.
• Cacheable: responses must say if they can be stored and reused.
• Uniform interface: one consistent way to address and act on resources.
• Layered system: a client cannot tell if it talks to the origin server.
• Code on demand (optional): the server may send runnable code, like JavaScript.

Every request stands alone, as this one does:

GET /articles/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Accept: application/json

Statelessness is the main trade-off. Any server node can handle any request, but each call must resend auth and context.

Resources are the key abstraction in REST. A resource is any information that can be named and addressed. Resources should be:

• Nouns, not verbs: Use /users not /getUsers
• Hierarchical: /users/123/orders/456
• Consistent: Use plural nouns (/users, not /user)
• Meaningful: Clear and descriptive names

Resources represent entities in your domain model and should map to business objects or data entities.

POST asks the server to create a new resource and choose its identifier. PUT creates or updates the resource at an identifier the client provides. So POST /users creates a new user, while PUT /users/123 creates or updates the user with ID 123.

The other difference is what a repeat does. POST is not idempotent, because multiple calls create multiple resources. PUT is idempotent, because multiple identical calls have the same effect as one.

The core codes are 200 OK, 400 Bad Request and 500 Internal Server Error. The first digit gives the class: 2xx means success, 4xx a client error and 5xx a server error.

• 200 OK for a successful GET, PUT or PATCH.
• 201 Created for a successful POST.
• 204 No Content for a successful DELETE or PUT with no response body.
• 400 Bad Request for invalid request syntax.
• 401 Unauthorized when authentication is required.
• 403 Forbidden when access is denied.
• 404 Not Found for a missing resource.
• 409 Conflict when the request conflicts with the current state.
• 422 Unprocessable Content when the body parses but fails validation.
• 500 Internal Server Error for a generic server error.
• 503 Service Unavailable when the server is temporarily unavailable.

Authentication checks who you are, and authorization checks what you may do. Authentication happens first, then authorization checks the permissions of the identity it proved.

The status codes follow the same split. Return 401 when credentials are missing or invalid, since the client needs to authenticate. Despite its name, 401 Unauthorized means unauthenticated. Return 403 when the server knows the caller but refuses the request. Secure APIs need both checks.

Reject the request with 422 Unprocessable Content and list every failing field, so the client can fix them all in one round trip. Use 400 Bad Request instead when the body can't be parsed at all, such as malformed JSON.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email must be valid format"
      },
      {
        "field": "password",
        "code": "TOO_SHORT",
        "message": "Password must be at least 8 characters"
      }
    ]
  }
}

Each entry carries three things.

• A field that names the input, so a form can highlight it.
• A stable error code, such as TOO_SHORT, that clients can handle in code.
• A human message for display.

Validate the whole body before acting, and return all the errors at once rather than stopping at the first. Keep the shape consistent with your other errors, or use the standard problem details format from RFC 9457 with an errors member.

Cross-Origin Resource Sharing (CORS) lets a server tell browsers which other origins may call it. By default a browser stops a page's script from reading another origin's responses, and CORS headers relax that rule in a controlled way.

An origin is the scheme, host and port together, so https://app.example.com and https://api.example.com are different origins. The server declares what it allows.

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 3600

For a request that isn't simple, such as a PUT or one with an Authorization header, the browser first sends a preflight OPTIONS request. Access-Control-Max-Age lets the browser cache that answer.

Handle it with a CORS library rather than by hand.

• Be specific with allowed origins, and don't use * for requests with credentials.
• Validate the Origin header against an allowlist on the server.
• CORS only guides browsers. Other clients ignore it, so it never replaces authentication.

REST APIs map each action on a resource to one of the HTTP methods.

• GET retrieves data from the server. It should be safe and idempotent.
• POST creates new resources or submits data for processing.
• PUT updates an entire resource, or creates it if it doesn't exist. It should be idempotent.
• PATCH partially updates a resource.
• DELETE removes a resource. It should be idempotent.
• HEAD works like GET but returns only headers, not the body.
• OPTIONS returns the methods allowed for a resource.

Here they are applied to one user resource.

GET /users/123        # Retrieve user with ID 123
POST /users           # Create a new user
PUT /users/123        # Update entire user 123
PATCH /users/123      # Partially update user 123
DELETE /users/123     # Delete user 123

These are related but distinct concepts:

URI (Uniform Resource Identifier):

• Generic term for any identifier that identifies a resource
• Superset that includes both URLs and URNs
• Example: mailto:john@example.com

URL (Uniform Resource Locator):

• Type of URI that specifies location and method to access a resource
• Includes protocol, domain, and path
• Example: https://api.example.com/users/123

URN (Uniform Resource Name):

• Type of URI that identifies a resource by name in a specific namespace
• Location-independent identifier
• Example: urn:isbn:0451450523

In REST APIs, we primarily work with URLs to locate and access resources over HTTP.

Protocol Buffers (protobuf) are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. gRPC uses protobuf for several reasons:

• Efficiency: Binary serialization is faster and more compact than JSON/XML
• Type Safety: Strongly typed schema prevents runtime errors
• Code Generation: Automatically generates client and server code
• Language Agnostic: Works across different programming languages
• Schema Evolution: Supports backward and forward compatibility

Example protobuf definition:

syntax = "proto3";

message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
}

service UserService {
  rpc GetUser(UserRequest) returns (User);
}

gRPC and REST differ mainly in the contract and the wire format. gRPC uses a strict Protocol Buffers contract, sends binary messages over HTTP/2 and streams in both directions. REST uses resources and HTTP verbs with JSON, which any browser or tool can read.

Choose gRPC for internal service-to-service calls where speed and typed clients matter. Choose REST for public and browser-facing APIs, where HTTP caching and plain JSON help more than raw speed.

HTTP/2 lets gRPC run many calls at once over one connection, in a compact binary format.

• Multiplexing sends many requests and responses at the same time over a single connection.
• Binary framing is cheaper to parse than the text protocol of HTTP/1.1.
• Header compression with HPACK cuts the bytes spent on repeated headers.
• Flow control stops a fast sender from overwhelming a slow receiver.
• Reusing one connection avoids new handshakes and cuts latency.

HTTP/2 also defines server push, but gRPC doesn't use it. The grpc-java client turns push off in its HTTP/2 settings, for example. Server streaming covers the case of many responses to one request.

gRPC supports four types of service methods:

1. Unary RPC: Client sends one request, server returns one response

rpc GetUser(UserRequest) returns (User);

2. Server Streaming RPC: Client sends one request, server returns a stream of responses

rpc ListUsers(ListUsersRequest) returns (stream User);

3. Client Streaming RPC: Client sends a stream of requests, server returns one response

rpc CreateUsers(stream User) returns (CreateUsersResponse);

4. Bidirectional Streaming RPC: Both client and server send streams of messages

rpc Chat(stream ChatMessage) returns (stream ChatMessage);

SOAP is a protocol with a fixed XML message format, while REST is an architectural style. SOAP wraps every call in an XML envelope, and a SOAP service usually publishes a WSDL contract. REST APIs expose resources at URLs and act on them with standard HTTP methods, usually exchanging JSON.

Choose REST for most web and mobile APIs, where lighter payloads and HTTP caching matter. SOAP still fits enterprise systems that need a formal contract or message-level security, such as older banking and insurance integrations.

HATEOAS (Hypermedia as the Engine of Application State) means that API responses should include links to related actions or resources. This makes APIs self-discoverable and reduces client-server coupling.

Example response with HATEOAS:

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": "/users/123",
    "orders": "/users/123/orders",
    "edit": "/users/123",
    "delete": "/users/123"
  }
}

Benefits include improved API discoverability, reduced documentation needs, and easier API evolution.

Use PUT to replace a whole resource and PATCH for a partial update. With PUT, the body is the complete new version, so any field you omit should be reset to its default or null. With PATCH, the body carries only the fields to change.

PUT /users/123
{
  "name": "John Doe",
  "email": "john@example.com"
}
# Replaces entire user object

PATCH /users/123
{
  "email": "newemail@example.com"
}
# Only updates email field

PUT is idempotent, so a client can safely retry it. PATCH isn't guaranteed to be, because a patch such as "append an item" changes the result each time it runs. PATCH also sends less data. A PUT built from a stale copy can overwrite a field someone else just changed, so pair it with an ETag and an If-Match check.

Measure first, then fix the slowest part of the request path. Track latency percentiles such as the 99th alongside error rates, because an average hides the slow tail users notice. Distributed tracing and APM tools show where each slow request spends its time.

The database is the usual bottleneck. Index the columns your queries filter and join on, and check slow queries with EXPLAIN. Fix N+1 queries, where a loop runs one query per item, with a join or one batched query. Connection pooling avoids a new connection per request. Read replicas spread read load, but they can lag, so reads that must see a fresh write go to the primary.

Caching skips the work. Keep hot data in Redis with a TTL, and clear it when the data changes. Send Cache-Control and ETag headers, so clients, CDNs and an API gateway can reuse responses. An unchanged resource then comes back as a bodiless 304 Not Modified.

Then shrink the response. Field selection lets a client ask only for what it needs, as in GET /users?fields=id,name,email. Compress responses with gzip, paginate long lists, and leave related resources out until the client asks for them.

Move heavy work off the request path. Async processing and background job queues let the API answer at once with 202 Accepted. Splitting into microservices helps scaling, not latency, because every remote call adds a network hop.

Treat the API as a product other companies build on, so stability and developer experience matter as much as features. Partners can't redeploy on your schedule, so a breaking change costs far more than in an internal API.

1. Put developer experience first. Give partners clear documentation and an interactive API explorer. Add SDKs in popular languages and a sandbox environment.
2. Pick an access model. Public APIs are open to all developers, partner APIs have restricted access, and private APIs are for internal use.
3. Make onboarding self-service. Partners register and manage their own API keys. They pick a usage tier with billing, and know which support channels to use.

Offer the integration patterns partners expect. Webhook notifications and polling endpoints cover most needs. Add real-time APIs over WebSockets for live data and batch processing APIs for bulk work. Partners subscribe to webhook events through an endpoint like this one.

POST /partners/webhooks
Authorization: Bearer partner_token
{
  "url": "https://partner.com/webhook",
  "events": ["order.created", "order.updated"],
  "secret": "webhook_secret"
}