Naming Conventions for Resources
You'll learn how to name REST API resources consistently so developers can predict and understand your API structure at a glance.
When designing REST APIs, the way you name resources matters as much as what resources you expose. Consistent naming conventions make your API intuitive and reduce confusion. Three key decisions shape resource naming: plural vs singular, casing style, and abbreviation policy.
Plural vs Singular Nouns
Use plural nouns for collection resources. A collection like /users represents multiple user resources, so the plural form signals this clearly. Individual resources become /users/123, where the plural base path remains consistent. Some APIs use singular (/user/123), but this creates awkward reading: "user 123" sounds like you're addressing a person, not requesting their data. Stick with plurals.
Kebab-Case vs camelCase
Choose kebab-case for URLs. URLs are case-sensitive in REST (though domains aren't), and kebab-case (/customer-orders) is more readable than camelCase (/customerOrders) or snake_case (/customer_orders). It's also the web standard—most URLs you see daily use hyphens. CamelCase can cause issues because CustomerOrders and customerorders might be treated as different paths by some systems.
Avoiding Abbreviations
Spell out words completely. /usr might save three characters, but /users communicates clearly to everyone. Abbreviations force developers to memorize your shorthand—does msg mean message or massage? Does addr mean address or adder? Only abbreviate universally understood terms like id.
Think of it like street signs: "Main Street" is clearer than "Mn St" to a visitor, even if locals know both.
Key Takeaway: Use plural nouns, kebab-case formatting, and full words for resource names to create predictable, readable REST APIs that developers can navigate without constant documentation lookups.