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 focus on a critical best practice you should always consider when designing and implementing your APIs: naming conventions.

#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 often say that there is no such thing as a perfect naming convention. Some conventions are easier to follow and understand, while others can feel more complex. However, the most important aspect is to define a naming convention that fits your organization’s requirements and, more importantly, to apply it consistently. With that in mind, here are some best practices and recommendations to guide you.

Well-structured convention

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 all lowercase, 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

Download

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, you can buy (or help buy) my son a Star Wars Lego set!