# Resource naming follows REST conventions

- **Pattern:** `ab-000352` (`api-design.naming-conventions.resource-naming`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000352
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000352)

## Why it matters

Verb-in-URL anti-patterns like `/api/getUsers` or `/api/createPost` conflate the resource with the action, which belongs to the HTTP method. This makes APIs harder to understand, breaks REST tooling that assumes noun-based paths, and forces every new developer to learn an idiosyncratic convention rather than standard REST. iso-25010:2011 maintainability.modifiability degrades measurably: adding a new operation on a resource requires inventing a new verb path rather than adding an HTTP method to an existing noun endpoint.

## Severity rationale

High because inconsistent resource naming breaks REST tooling assumptions, makes APIs unintuitive for every new consumer, and compounds with each added endpoint.

## Remediation

Rename all verb-in-URL routes to noun-based equivalents and let the HTTP method carry the action. Update your `src/routes/` files:

```
// Before -- verbs in URLs:
GET  /api/getUsers
POST /api/createPost
GET  /api/user/1/getComments

// After -- nouns with HTTP method semantics:
GET    /api/users
POST   /api/posts
GET    /api/users/1/comments
DELETE /api/posts/42
```

For actions that don't map to CRUD (e.g., send invoice, approve request), use a sub-resource pattern: `POST /api/invoices/42/send`.

## Detection

- **ID:** `resource-naming`
- **Severity:** `high`
- **What to look for:** Examine all API route paths. For REST APIs, check that resource names are nouns (not verbs), collections use plural forms, and nesting reflects relationships. Look for anti-patterns: `/api/getUsers` (verb in URL), `/api/user` (singular collection), `/api/createPost` (action in URL instead of HTTP method), `/api/user/1/getComments` (verb in nested resource). For GraphQL, check that query names use nouns (`users`, `user`) and mutations use verb+noun (`createUser`, `updatePost`). For gRPC, check that service names are nouns and RPC method names follow `Verb+Noun` convention.
- **Pass criteria:** Enumerate all API route paths. At least 80% of REST endpoints use plural nouns for collections and singular nouns for individual resources. URL paths do not contain verbs (actions are expressed via HTTP methods). Count every route that uses a verb in the path (e.g., `getUsers`, `createPost`, `deleteItem`) and report the ratio of compliant routes to total routes. GraphQL queries/mutations follow naming conventions. gRPC services and methods follow the Protobuf style guide. Report the count of compliant vs non-compliant routes even on pass.
- **Fail criteria:** Routes mix verbs and nouns in URLs (e.g., `/api/getUsers` alongside `/api/posts`). Collection endpoints use inconsistent singular/plural naming. Actions are encoded in the URL path instead of using HTTP methods. Quote the specific violating route paths found.
- **Skip (N/A) when:** Fewer than 2 API endpoints exist. Also skip for RPC-only APIs that intentionally use action-based naming (check for documentation stating this is intentional).
- **Detail on fail:** Name the specific violations found (e.g., "Routes mix verb-based naming (`/api/getUsers`, `/api/deletePost`) with noun-based naming (`/api/comments`). Collections inconsistently use `/api/user` (singular) and `/api/posts` (plural). 4 of 10 routes use verbs in paths."). Max 500 chars.
- **Remediation:** REST APIs should use nouns for resource paths and let HTTP methods convey the action. Collections should be plural. In Express/Fastify, update your `src/routes/` files:
- **Cross-reference:** For endpoint security concerns like auth and rate limiting on these routes, see the SaaS API Design audit.

  ```
  // Before -- verbs in URLs:
  GET  /api/getUsers
  POST /api/createPost
  GET  /api/user/1/getComments

  // After -- nouns with HTTP method semantics:
  GET    /api/users
  POST   /api/posts
  GET    /api/users/1/comments
  DELETE /api/posts/42
  ```

  For actions that don't map cleanly to CRUD (e.g., "send invoice", "approve request"), use a sub-resource pattern: `POST /api/invoices/42/send` or `POST /api/requests/42/approval`.

## External references

- iso-25010 maintainability.modifiability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000352