REST API Design Best Practices: A Practical Guide for 2026

Every team builds APIs. Few build ones that survive their second rewrite. After inheriting three different REST APIs in as many years — one with endpoints named /getAllUsers , another that returned { "status": "ok" } for both success and 500 errors — I started keeping a list of the practices that actually distinguish robust APIs from ones that generate PagerDuty alerts at 3 AM. This guide distills six rules I've validated across production services handling tens of millions of requests. None are theoretical. All come with working code. 1. Resource-Oriented Naming — Not Action-Oriented The single biggest smell in a REST API is action verbs in URLs: # Bad — these are RPC, not REST GET /api/getUser?id=42 POST /api/createUser POST /api/deleteUser/42 POST /api/activateUserSubscription Resources are nouns, not verbs. The HTTP method is the verb: # Good GET /api/users/42 POST /api/users DELETE /api/users/42 POST /api/users/42/subscriptions # nested resource DELETE /api/users/42/subscriptions/active Key conventions that have held across every production API I've consulted on: Plural nouns : /users , not /user . Consistency with list endpoints ( GET /users = a list) makes singular feel like a bug. Kebab-case for multi-word resources : /order-items , not /orderItems or /order_items . It's URL-safe and matches what browsers expect. Nest at most two levels : /users/42/orders/7 is fine. /users/42/orders/7/items/3/addresses/9 is a cry for help. At that point, use a query parameter: /items?order_id=7 . Use query params for filtering, not path segments : /users?status=active&role=admin , not /users/active/admins . 2. Consistent Error Responses — The Contract People Actually Rely On Most API errors are parsable only by humans staring at a screen. That's a bug. Every error response should follow the same schema so clients can handle them programmatically: { "error": { "code": "USER_NOT_FOUND", "message": "User with id 42 was not found.", "details": { "resource": "users", "identifier"