# Resources and URLs — API Design and Versioning

Source: https://www.geekswithgeeks.com/en/api-design/pr-resources-urls

> Model nouns as resources with consistent, predictable 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.

```text
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.

**Quiz:** Which URL follows resource-oriented design?

- [x] GET /orders/42
- [ ] GET /fetchOrderNumber42
- [ ] POST /doDeleteOrder
- [ ] GET /orders/getById?id=42

*Answer:* GET /orders/42. A plural noun plus an identifier names the resource; the method supplies the action.