claudekit/.claude/skills/api/openapi/references/rest-naming.md

REST API Naming Conventions

Guidelines for consistent, predictable REST endpoint design.

---

Core Rules

1. Use plural nouns for resource collections
2. Use kebab-case for multi-word resources
3. Use path parameters for identity, query parameters for filtering
4. Never use verbs in URLs (HTTP methods convey the action)
5. Use lowercase exclusively

---

Resource Naming

Pattern	Example	Notes
Collection	/users	Plural noun
Single resource	/users/{id}	Path parameter
Multi-word resource	/order-items	Kebab-case
Nested resource	/users/{id}/orders	Parent-child relationship
Deep nesting (avoid)	/users/{id}/orders/{oid}/items	Max 2 levels deep
Singleton sub-resource	/users/{id}/profile	One-to-one relationship

Good

GET    /users
GET    /users/123
POST   /users
PUT    /users/123
DELETE /users/123
GET    /users/123/orders
GET    /order-items
GET    /user-profiles/123

Bad

GET    /getUsers            # verb in URL
GET    /user/123            # singular collection
GET    /Users               # uppercase
POST   /users/create        # redundant verb
GET    /user_profiles       # snake_case
DELETE /users/123/delete     # verb in URL

---

CRUD Mapping

Action	Method	Endpoint	Request Body	Response
List	GET	/resources	None	200 + array
Create	POST	/resources	Resource data	201 + created
Read	GET	/resources/{id}	None	200 + object
Update (full)	PUT	/resources/{id}	Full resource	200 + updated
Update (partial)	PATCH	/resources/{id}	Partial data	200 + updated
Delete	DELETE	/resources/{id}	None	204

---

Nested Resources

Use nesting to express clear parent-child relationships.

# User's orders (user owns orders)
GET  /users/{userId}/orders
POST /users/{userId}/orders

# Order's line items
GET  /orders/{orderId}/items

When to nest vs. top-level:

Scenario	Approach	Example
Resource only exists under parent	Nest	/users/{id}/sessions
Resource is independently accessible	Top-level with filter	/orders?user_id=123
Shallow relationship	Top-level	/comments?post_id=456

Rule of thumb: Never nest more than 2 levels. Use query parameters or top-level endpoints instead.

# Too deep -- avoid
GET /users/{id}/orders/{oid}/items/{iid}/reviews

# Better alternatives
GET /order-items/{iid}/reviews
GET /reviews?order_item_id={iid}

---

Query Parameters

Filtering

GET /products?category=electronics&brand=acme
GET /users?status=active&role=admin
GET /orders?created_after=2025-01-01&created_before=2025-02-01

Convention	Example
Exact match	?status=active
Date range	?created_after=2025-01-01
Multiple values	?status=active,pending
Search	?q=search+term

Sorting

GET /products?sort=price         # ascending (default)
GET /products?sort=-price        # descending (prefix -)
GET /products?sort=-created_at,name  # multi-field

Pagination

# Offset-based (simple, common)
GET /products?page=2&per_page=25

# Cursor-based (better for large datasets)
GET /products?cursor=eyJpZCI6MTAwfQ&limit=25

Response envelope for paginated results:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

Field Selection

GET /users/123?fields=id,name,email

---

Non-CRUD Actions

Some operations do not map cleanly to CRUD. Use sub-resources with a noun or POST with an action resource.

Action	Approach	Example
Send an email	POST to action resource	POST /users/{id}/verification-email
Archive	PATCH with status	PATCH /orders/{id} { "status": "archived" }
Bulk delete	POST to action	POST /users/bulk-delete { "ids": [...] }
Export	GET with format	GET /reports/sales?format=csv
Search (complex)	POST with body	POST /products/search { "filters": {...} }

---

Versioning

Strategy	Example	Pros	Cons
URL path	/api/v1/users	Simple, explicit	URL pollution
Header	Accept: application/vnd.api.v1+json	Clean URLs	Hidden
Query param	/users?version=1	Easy to test	Caching issues

Recommended: URL path versioning (/api/v1/) for public APIs due to simplicity.

---

Summary Checklist

• Resources are plural nouns (/users not /user)
• URLs are kebab-case and lowercase
• No verbs in URLs
• Nesting limited to 2 levels
• Filtering uses query parameters
• Sorting supports -field for descending
• Pagination included on all list endpoints
• API version in URL path for public APIs
• Consistent error response format

Reference: Google API Design Guide, Microsoft REST Guidelines