What is the difference between PUT and PATCH for updating a resource?

PUT replaces the entire resource. If you send a PUT request with only the name field, the API should update the resource so that only the name field exists — all other fields are cleared or reset to defaults. PUT is idempotent: sending the same PUT request multiple times produces the same result. PATCH applies a partial update — only the fields you include in the request body are changed; others remain untouched. PATCH is appropriate when clients know only the fields they want to change. In practice, most APIs implement "partial PUT" (treating PUT like PATCH) because full replacement is destructive and unexpected, but the REST standard is clear on the distinction.

What HTTP status code should I return for field validation errors?

422 Unprocessable Entity is the correct status code for validation failures where the request is syntactically valid (correct JSON, correct Content-Type) but semantically invalid (missing required field, invalid email format, value out of allowed range). Many APIs incorrectly use 400 Bad Request for validation errors — 400 should be reserved for requests that are structurally malformed (invalid JSON, wrong Content-Type). The distinction matters for client error handling: a 400 suggests the client code has a bug, while a 422 suggests user input needs correction. Always include the specific field errors in the response body so the client can surface them in the UI.

How should I version my API without breaking existing clients?

The safest approach is to never make breaking changes within a version (v1 stays backward compatible forever) and introduce v2 only when fundamental design changes are needed. A breaking change is: removing a field from a response, changing a field's type, removing an endpoint, or changing authentication behavior. Additive changes (new optional fields, new endpoints) are not breaking and should not require a version bump. When you do release v2, maintain v1 for a deprecation period (typically 6-12 months), communicate the sunset date clearly in documentation and response headers, and provide a migration guide. URL path versioning (/api/v1/) is the most practical strategy for most teams.

What is the difference between 401 Unauthorized and 403 Forbidden?

401 Unauthorized means the request lacks valid authentication credentials — the server cannot identify who the client is. The client should authenticate (log in, refresh token, include API key) and retry. Despite the name "Unauthorized," it really means "Unauthenticated." 403 Forbidden means the server knows exactly who the client is (they are authenticated) but that user does not have permission to access the requested resource. The client should not retry with the same credentials — they need elevated permissions. A practical test: if a visitor who is not logged in gets the same response as a logged-in user without permissions, you are probably using 401 when you should use 403.

How do I implement cursor-based pagination and when should I use it?

Cursor-based pagination works by encoding the position in the dataset as an opaque token rather than a page number. Implementation: your SELECT query includes WHERE id &limit=20 on subsequent requests. Use cursor pagination for: social feeds, activity logs, chat messages, any list where new items are frequently inserted (offset pagination would skip or duplicate records as data shifts). Use offset pagination when: users need to jump to an arbitrary page, data is static or append-only, or "page 5 of 10" navigation is a product requirement.

Engineering·10 min read·June 20, 2026

🔌 REST API Design Best Practices for Modern Web Applications

A comprehensive guide to REST API design: resource naming conventions, HTTP method semantics, status codes, versioning strategies, authentication patterns, rate limiting, pagination, and OpenAPI 3.0 documentation.

📖Full-Stack SaaS with Next.js, Supabase & Groq AI (Full Access)

View →

Why API Design Decisions Are Permanent

API design decisions are uniquely consequential because APIs are public contracts. Once clients depend on your endpoint structure, status codes, or response shapes, changing them breaks their code. The patterns in this guide are not preferences — they are conventions that exist because they prevent breaking changes, reduce client-side bugs, and make your API predictable to any developer who has worked with REST before.

Topics covered

REST API designAPI best practicesHTTP status codesAPI versioning strategiesREST resource namingAPI authentication JWTAPI rate limiting headerscursor-based paginationOpenAPI 3.0 documentationHTTP methods RESTAPI error response formatBearer token APIAPI design guideREST API conventionsAPI rate limit 429401 vs 403 APIoffset vs cursor paginationAPI response envelopeREST API URL structure