Resource Naming Fundamentals

One of the most important aspects of REST API design is how you name your resources. Good naming makes your API intuitive and self-documenting.

Resources vs Actions

In REST, URIs identify resources (nouns), not actions (verbs). The HTTP method provides the action.

Bad (verb-based):

GET /getUsers
POST /createUser
PUT /updateUser/123
DELETE /deleteUser/123

Good (noun-based):

GET /users
POST /users
PUT /users/123
DELETE /users/123

Use Plural Nouns

Use plural nouns for consistency, even for single resource access.

Bad:

GET /user/123
GET /users

Good:

GET /users/123
GET /users

This consistency makes the API easier to learn and use.

Use Lowercase Letters

URIs should use lowercase letters. This avoids confusion since URLs are case-sensitive in some contexts.

Bad:

/Users/123
/UserPosts

Good:

/users/123
/user-posts

Use Hyphens for Readability

Use hyphens (-) to separate words in resource names, not underscores or camelCase.

Bad:

/user_profiles
/userProfiles

Good:

/user-profiles

Hyphens are more readable and SEO-friendly.

Hierarchical Relationships

Use path segments to express relationships between resources.

/users/123/orders          # Orders belonging to user 123
/orders/456/items          # Items in order 456
/categories/books/products # Products in the books category

Collection vs Document

• Collection: A directory of resources (plural noun)
• Document: A single resource instance (identified by ID)

/users              # Collection of users
/users/123          # Document: specific user

/products           # Collection of products
/products/abc       # Document: specific product

Exercise: Fix Resource Names

Common Mistakes to Avoid

1. Don't Include File Extensions

Bad:  /users.json
Good: /users (use Accept header for format)

2. Don't Use Query Strings for Resource Identification

Bad:  /users?id=123
Good: /users/123

3. Don't Nest Too Deeply

Bad:  /countries/us/states/ca/cities/sf/neighborhoods/mission/streets
Good: /streets?city=sf (or /cities/sf/streets)

4. Don't Mix Singular and Plural

Bad:  /user/123/orders
Good: /users/123/orders

Summary Table

Guideline	Bad Example	Good Example
Use nouns	/getUsers	/users
Use plurals	/user/123	/users/123
Use lowercase	/Users	/users
Use hyphens	/user_profiles	/user-profiles
Show hierarchy	/getUserOrders?id=123	/users/123/orders

Good resource naming is foundational to good API design. In the next lesson, we'll dive deeper into URI design best practices.