Should I use plural or singular nouns for REST API resource names?

Use plural nouns consistently. /users represents the collection of users and /users/42 represents a specific user within that collection. Mixing singular and plural creates confusion about whether an endpoint returns one item or many. The only exception is singleton resources like /users/42/profile where exactly one profile exists per user.

When should I use PUT vs PATCH for updates?

Use PUT when the client sends the complete resource representation and the server replaces the existing resource entirely. Missing fields in a PUT request should be set to null or default values. Use PATCH when the client sends only the fields that changed. PATCH is more bandwidth-efficient and avoids accidental data loss from omitted fields. Most APIs use PATCH for updates because clients rarely need to replace an entire resource.

How do I choose between offset and cursor-based pagination?

Offset-based pagination (page=3 and limit=10) is simple to implement and lets clients jump to arbitrary pages, but it degrades on large datasets because the database must skip N rows. It also produces inconsistent results if items are inserted or deleted between requests. Cursor-based pagination (after=abc123) is more efficient because it uses indexed lookups and produces consistent results regardless of concurrent modifications. Use cursor-based for large or frequently changing datasets and offset-based for small, mostly static collections.

Should I put the API version in the URL or a header?

URL path versioning like /v1/users is the most practical choice for most teams. It is visible, easy to test with curl, simple to route in load balancers, and unambiguous in documentation. Header versioning using Accept: application/vnd.example.v2+json produces cleaner URLs but makes testing harder, complicates caching, and is invisible in server logs. GitHub uses header versioning successfully but most APIs benefit from the simplicity of URL versioning.

What is RFC 7807 and should I use it for API errors?

RFC 7807 defines a standard format for HTTP API error responses called Problem Details. It specifies fields like type (URI identifying the error category), title (human-readable summary), status (HTTP status code), detail (specific explanation), and instance (URI of the failing request). Using it ensures all your errors follow a consistent, parseable structure that client libraries can handle generically. It is widely supported and recommended by API design guides from Google, Microsoft, and the IETF.

Structuring REST APIs to Avoid Common Errors