Consistency in naming conventions separates professional enterprise APIs from ad-hoc internal endpoints. Adopting predictable casing rules across URIs, parameters, and payload keys simplifies SDK generation and client integration.
1. Standard Casing Rules Summary
| API Target | Recommended Casing | Correct Example | Incorrect Example |
|---|---|---|---|
| URI Paths | lower-kebab-case | /v1/user-profiles | /v1/userProfiles or /v1/user_profiles |
| Path Parameters | camelCase or lower-kebab-case | /v1/users/{userId} | /v1/users/{user_id} |
| Query Parameters | camelCase | ?startingAfter=usr_100 | ?starting_after=usr_100 |
| JSON Keys | camelCase | {"firstName": "Jane"} | {"first_name": "Jane"} |
| HTTP Headers | Train-Case (Hyphenated) | X-Request-ID | x_request_id or requestid |
Canonical Casing Standards across API Surface
2. Resource Path Rules
- Use Plural Nouns: Represent resource collections with plural nouns (e.g. /v1/orders, /v1/products).
- Avoid Verbs in Path: Use HTTP methods (POST, DELETE) to express actions instead of /v1/createOrder.
- Nested Resources: Limit nested hierarchy depth to 2 levels (e.g. /v1/users/{userId}/orders). If deeper relations are needed, make sub-resources top-level with query filters.
Check API Naming Quality Automatically
Scan your specification with APIForge to catch mixed casing, path verbs, and deeply nested URIs instantly.