API Management Best Practices, Tips, and Tricks #6 URL’s structure and naming convention

Here we are, ready for another edition of API Management Best Practices, Tips, and Tricks. Today, we will address another helpful Best practice, Tip, and Trick that you must consider while implementing your API’s: Naming convention.

#6 URL’s structure and naming convention

REST API resource naming convention defines how API endpoints (URIs) should be structured to ensure clarity, consistency, and scalability. It focuses on making API URLs predictable, readable, and RESTful by following best practices.

I usually say that there is no perfect naming convention. There may be some that are easy to follow and understand, and some that are harder to follow. However, the important thing is to have a proper naming convention to fit your organization’s requirements, and to follow it. But here are some best practices and suggestions.

A well-structured naming convention typically follows these principles:

• A URL path is the portion of a URL that specifies the location of a resource on a server. It comes after the domain name and typically follows a hierarchical structure to represent different levels of data.
  • Use nouns, not verbs, to represent resources
    • ✅ /users
    • ❌ /getUsers
  • Use plural form for resources (collections)
    • ✅ /orders
    • ❌ /order
  • Organize resources hierarchically to show relationships when necessary
    • ✅ /users/{user-id}/orders
  • Avoid verbs in URLs
    • ✅ DELETE /users/{id}
  • Keep URLs lowercase and use hyphens instead of underscores
    • ✅ /user-profiles
  • For URL Paths, we should use Kebab-case (lowercase with hyphens) notation.
    • The reason for using a naming convention is that hyphens improve readability and are easier to type in URLs. Another important reason is that spaces are not allowed in URLs.

• A URI parameter (also called a path parameter) is part of the URL path and is typically used to identify a specific resource. These parameters are mandatory and help in defining hierarchical relationships.
  • They should follow kebab-case notation for the same reason we described above.
    • GET /products/{product-id}/reviews

• A query parameter is part of the query string, which appears after a ? in the URL and is used to filter, sort, or provide additional options for a request. Query parameters are written as key-value pairs.
  • Use camelCase or snake_case for query parameters, depending on the system’s standard. Both are readable and common in different APIs.
    • ✅GET /users?sortBy=name
    • ✅GET /products?filter_by=category
  • Avoid these practices:
    • Do NOT use kebab-case in query parameters (some frameworks don’t support it well)
    • ALLUPPERCASE or alllowercase, those conventions are hard to read.

URL Naming Convention Summary

Context	Best Practice	Example
URLs (paths)	kebab-case	GET /user-accounts
URI Parameters	kebab-case	GET /users/{user-id}
Query Parameters	camelCase or snake_case	?filterBy=category ?sort_by=name

Know more about naming conventions and API best practices in my whitepaper: Mastering API Best Practices Enforcing Best Practices with Azure API Management.

I hope you enjoy this tip and stay tuned for the following Azure API Management Best practices, Tips, and Tricks.

If you liked the content or found it helpful and want to help me write more content, you can buy (or help buy) my son a Star Wars Lego!