Noun-based resource naming in Rest API - Step-by-Step Execution

Concept Flow - Noun-based resource naming

Client sends HTTP request

↓

Request targets resource URL

↓

Resource named as noun (e.g., /users)

↓

Server processes request on resource

↓

Server returns response with resource data

The client sends a request to a URL named as a noun representing the resource. The server processes this noun-based resource and returns the appropriate data.

Execution Sample

Rest API

GET /users HTTP/1.1
Host: example.com

Response: 200 OK
[
  {"id":1,"name":"Alice"},
  {"id":2,"name":"Bob"}
]

A client requests the 'users' resource using a noun-based URL and receives a list of users.

Execution Table

Step	HTTP Method	URL	Resource Name	Action	Response
1	GET	/users	users	Retrieve list of users	200 OK with user list
2	POST	/users	users	Create new user	201 Created with new user data
3	GET	/users/1	users	Retrieve user with id=1	200 OK with user data
4	PUT	/users/1	users	Update user with id=1	200 OK with updated data
5	DELETE	/users/1	users	Delete user with id=1	204 No Content
6	-	-	-	-	Request ends

💡 All requests target noun-based resource URLs; execution stops after response.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	Final
HTTP Method	-	GET	POST	GET	PUT	DELETE	-
URL	-	/users	/users	/users/1	/users/1	/users/1	-
Resource Name	-	users	users	users	users	users	-
Response Status	-	200 OK	201 Created	200 OK	200 OK	204 No Content	-

Key Moments - 3 Insights

Why do we use nouns like '/users' instead of verbs like '/getUsers' in URLs?

Because REST APIs treat URLs as resources (things), not actions. Actions are expressed by HTTP methods (GET, POST, etc.). See execution_table rows 1 and 2 where GET and POST act on the noun 'users'.

How does the server know what action to perform if the URL is just a noun?

The HTTP method tells the server the action (GET to read, POST to create, etc.). The URL identifies the resource. This is shown in execution_table where the same URL '/users' is used with different methods.

What happens if we add an ID after the noun, like '/users/1'?

It specifies a single resource instance. The server performs actions on that specific user. See execution_table rows 3-5 for examples.

Visual Quiz - 3 Questions

Look at the execution_table, what HTTP method is used to update a user?

A GET

B PUT

C POST

D DELETE

💡 Hint

Check the 'HTTP Method' column in execution_table row 4.

At which step does the server respond with '201 Created'?

A Step 2

B Step 1

C Step 3

D Step 5

💡 Hint

Look at the 'Response' column in execution_table row 2.

If the URL changed from '/users' to '/getUsers', what principle would this break?

A Using HTTP methods for actions

B Using verbs for resource naming

C Using nouns for resource naming

D Using query parameters

💡 Hint

Refer to key_moments question about noun vs verb naming.

Concept Snapshot

Use nouns to name resources in URLs (e.g., /users).
Use HTTP methods (GET, POST, PUT, DELETE) to specify actions.
Add resource IDs to target specific items (e.g., /users/1).
Avoid verbs in URLs; keep URLs simple and resource-focused.
This makes APIs clear, consistent, and easy to use.

Full Transcript

In REST APIs, resource URLs should be named using nouns that represent the resource, like '/users'. The HTTP method (GET, POST, PUT, DELETE) tells the server what action to perform on that resource. For example, GET /users retrieves a list of users, POST /users creates a new user, and GET /users/1 retrieves a specific user by ID. This approach keeps URLs simple and focused on resources, while actions are handled by HTTP methods. Using verbs in URLs like '/getUsers' is discouraged because it mixes resource naming with actions. This visual trace showed each step of requests and responses, how variables like HTTP method and URL change, and clarified common confusions about noun-based resource naming.

Practice

1. Which of the following is the best example of a noun-based resource name for a REST API endpoint that manages multiple books?

easy

A. /fetchBooks

B. /getBooks

C. /bookAction

D. /books

Solution

1. Step 1: Understand noun-based resource naming

   Noun-based naming uses plural nouns to represent collections of resources, making the API intuitive.

2. Step 2: Identify the correct plural noun path

   Among the options, only '/books' is a plural noun representing the resource collection without verbs or actions.

3. Final Answer:

   /books -> Option D

4. Quick Check:

   Noun-based resource = /books [OK]

Hint: Use plural nouns without verbs for resource paths [OK]

Common Mistakes:

• Including verbs like 'get' or 'fetch' in the URL
• Using singular nouns for collections
• Adding action words in resource names

2. Which of the following is the correct REST API endpoint syntax for accessing a single user resource by ID?

easy

A. /users/get/123

B. /user?id=123

C. /users/123

D. /getUser/123

Solution

1. Step 1: Review REST API syntax for single resource

   Single resources are accessed by appending the resource ID to the plural noun path.

2. Step 2: Identify the correct syntax

   Option '/users/123' correctly uses the plural noun 'users' followed by the ID without verbs or query parameters.

3. Final Answer:

   /users/123 -> Option C

4. Quick Check:

   Single resource path = /users/123 [OK]

Hint: Use /resourceName/{id} for single resource access [OK]

Common Mistakes:

• Adding verbs like 'get' in the path
• Using query parameters instead of path variables
• Using singular noun without ID

3. Given the REST API endpoint GET /orders/456, what does this request represent?

medium

A. Retrieve the order with ID 456

B. Create a new order with ID 456

C. Delete the order with ID 456

D. Update the order with ID 456

Solution

1. Step 1: Understand HTTP GET method

   GET is used to retrieve or read data from the server without modifying it.

2. Step 2: Interpret the endpoint path

   The path '/orders/456' points to a single order resource with ID 456.

3. Final Answer:

   Retrieve the order with ID 456 -> Option A

4. Quick Check:

   GET /orders/456 = Retrieve order 456 [OK]

Hint: GET + /resource/{id} means fetch that resource [OK]

Common Mistakes:

• Confusing GET with POST or DELETE actions
• Assuming the request modifies data
• Misreading the resource ID

4. Identify the error in this REST API endpoint for deleting a user: DELETE /deleteUser/789

medium

A. Missing query parameter for user ID

B. Using a verb 'deleteUser' in the resource path

C. Using DELETE method instead of GET

D. Using plural noun instead of singular

Solution

1. Step 1: Check resource naming conventions

   Resource paths should be nouns, not verbs or actions.

2. Step 2: Analyze the given endpoint

   The path '/deleteUser/789' incorrectly includes the verb 'deleteUser' instead of just '/users/789'.

3. Final Answer:

   Using a verb 'deleteUser' in the resource path -> Option B

4. Quick Check:

   Resource path must be noun, not verb [OK]

Hint: Avoid verbs in paths; use HTTP methods for actions [OK]

Common Mistakes:

• Including action verbs in URL paths
• Confusing HTTP method with URL naming
• Using query parameters unnecessarily

5. You want to design a REST API for managing comments on blog posts. Which of the following is the best noun-based resource path to list all comments for a post with ID 42?

hard

A. /posts/42/comments

B. /getCommentsForPost/42

C. /comments?postId=42

D. /postComments/42

Solution

1. Step 1: Understand nested resource naming

   Comments belong to posts, so nesting comments under posts is clear and RESTful.

2. Step 2: Evaluate the options

   Option '/posts/42/comments' uses plural nouns and shows the relationship clearly without verbs or query parameters.

3. Final Answer:

   /posts/42/comments -> Option A

4. Quick Check:

   Nested plural nouns show resource hierarchy [OK]

Hint: Use nested plural nouns for related resources [OK]

Common Mistakes:

• Using verbs in paths like 'getCommentsForPost'
• Using query parameters instead of nested paths
• Using singular nouns inconsistently