Resources and URLs

Nouns in the path, verbs in the method

In a REST-style API the URL names a resource (a thing) and the HTTP method says what to do with it. Use plural nouns (/orders, /orders/42), lowercase words separated by hyphens, and nesting only when ownership is real (/orders/42/items), going no deeper than about two levels. Avoid verbs in paths (/getOrder, /createUser). For operations that are not simple CRUD, model the action as a sub-resource or event (POST /orders/42/cancellation, POST /payments/pay_1/refunds) rather than a free-form RPC name. Keep identifiers opaque and stable, never reuse them, and do not expose auto-increment numbers if enumeration is a risk.

Good and poor URL design

Compare the verb-heavy style with resource-oriented design. Both columns do the same jobs.

Poor                                  Better
GET  /getAllOrders                    GET    /orders
POST /createOrder                     POST   /orders
GET  /order?id=42                     GET    /orders/42
POST /deleteOrder/42                  DELETE /orders/42
POST /cancelOrder/42                  POST   /orders/42/cancellation
GET  /customers/42/orders/7/items/3/x flatten: GET /order-items/3

Be boring and consistent

Pick one convention for plural names, casing (snake_case or camelCase in JSON, not both), dates (ISO 8601) and ids, then apply it everywhere. Predictability beats cleverness.

Quick check: Which URL follows resource-oriented design?

• GET /orders/42
• GET /fetchOrderNumber42
• POST /doDeleteOrder
• GET /orders/getById?id=42