textANYrestpathskebab-case
text
/purchase-orders
/api-keysKebab-case is common in URLs because it is readable and avoids case-sensitivity surprises.
REST API Resource Naming and URL Design
Naming conventions for resources, relationships, nested endpoints, and clean URL design.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Naming conventions
Keep endpoint names predictable and uniform.
textANYrestcontent-negotiationpaths
text
Prefer: GET /reports/123
Avoid: GET /reports/123.jsonContent negotiation and media types are usually cleaner than path-based format suffixes.
textANYrestrelationshipsnested
text
GET /teams/{teamId}/membersA relationship collection should read clearly from left to right and preserve the domain meaning.
textANYrestnestingurls
text
Better: /orders/{orderId}/items
Avoid: /customers/{customerId}/orders/{orderId}/items/{itemId}/notesDeeply nested URLs become harder to maintain, document, and cache.
textANYrestcanonicalresources
text
/orders/{orderId}
/order-items/{itemId}Even if a resource is reachable through a nested route, it often helps to expose a canonical direct path for the item itself.
Path vs query parameters
Put identity in the path and modifiers in the query string.
httpANYrestpath-paramsidentity
http
GET /users/123The path identifies the thing the request is about.
httpANYrestqueryfiltering
http
GET /users?role=admin&status=activeQuery parameters are a better fit for filtering, sorting, searching, pagination, and sparse fieldsets.
httpANYrestprojectionfields
http
GET /users/123?fields=id,name,emailSparse fieldsets can reduce payload size and overfetching in large representations.
httpANYrestincludeembedding
http
GET /orders/ord_123?include=customer,itemsOptional includes can reduce round trips while keeping the base response lightweight.
More in REST API
REST API Best Practices and Anti-Patterns
High-signal design rules, consistency patterns, and common mistakes to avoid in production APIs.
REST API Request and Response Patterns
JSON request bodies, envelope choices, sparse fieldsets, includes, concurrency control, and common response contracts.
REST API Authentication, Authorization, and Versioning
Bearer auth, API keys, permission errors, versioning strategies, and compatibility patterns for HTTP APIs.
REST API Status Codes and Error Response Design
Practical HTTP status codes, error response bodies, validation failures, and troubleshooting-friendly API error contracts.
REST API Pagination, Filtering, Sorting, and Search
Common collection query patterns including offset pagination, cursor pagination, filtering, sorting, and search.
REST API Methods and Idempotency
HTTP methods, safe vs unsafe semantics, and idempotency examples for API consumers and designers.