Mastering RESTful URI Design: Naming Conventions for Clear APIs

In REST, the primary data is called a resource, and well‑named resources make an API intuitive and easy to use; poor naming can make the API feel complex and hard to understand.

Use nouns, not verbs, to represent resources

Always name your URI with a noun that identifies the resource; avoid verb‑noun combinations and naming styles such as hyphenated, snake_case, or camelCase.

http://api.example.com/v1/store/CreateItems/{item-id} ❌
http://api.example.com/v1/store/getEmployees/{emp-id} ❌
http://api.example.com/v1/store/update-prices/{price-id} ❌
http://api.example.com/v1/store/deleteOrders/{order-id} ❌

http://api.example.com/v1/store/items/{item-id} ✅
http://api.example.com/v1/store/employees/{emp-id} ✅
http://api.example.com/v1/store/prices/{price-id} ✅
http://api.example.com/v1/store/orders/{order-id} ✅

Use plural nouns for collections

Prefer plural nouns for resources unless they represent a singleton.

http://api.example.com/v1/store/item/{item-id} ❌
http://api.example.com/v1/store/employee/{emp-id}/address ❌

http://api.example.com/v1/store/items/{item-id} ✅
http://api.example.com/v1/store/employees/{emp-id}/address ✅

Use hyphens (-) for readability

Separate words with hyphens instead of underscores; this improves readability, especially for long path segments.

http://api.example.com/v1/store/vendormanagement/{vendor-id} ❌
http://api.example.com/v1/store/itemmanagement/{item-id}/producttype ❌
http://api.example.com/v1/store/inventory_management ❌

http://api.example.com/v1/store/vendor-management/{vendor-id} ✅
http://api.example.com/v1/store/item-management/{item-id}/product-input ✅
http://api.example.com/v1/store/inventory-management ✅

Use forward slash (/) for hierarchy, but not at the end

Use slashes to show hierarchy between single resources and collections; avoid a trailing slash.

http://api.example.com/v1/store/items/ ❌

http://api.example.com/v1/store/items ✅

Avoid file extensions

File extensions add unnecessary length and complexity to URIs.

http://api.example.com/v1/store/items.json ❌
http://api.example.com/v1/store/products.xml ❌

http://api.example.com/v1/store/items ✅
http://api.example.com/v1/store/products ✅

Version your API

Always version your API to provide an upgrade path without breaking existing clients.

http://api.example.com/v1/store/employees/{emp-id}

http://api.example.com/v1/store/items/{item-id}
http://api.example.com/v2/store/employees/{emp-id}/address

Use query parameters to filter collections

Enable sorting, filtering, and pagination via query parameters instead of creating extra endpoints.

http://api.example.com/v1/store/items?group=124
http://api.example.com/v1/store/employees?department=IT®ion=USA

Example CRUD operations

GET – Retrieve employee with ID 8345 example.com/employees/8345 POST – Create a new employee example.com/employees PUT – Update employee ID 8345 example.com/employees/8345 DELETE – Remove employee ID 8345

example.com/employees/8345