Endpoint Design, Naming Conventions, URI Structure, and Versioning
Design REST endpoints that stay readable, scalable, and maintainable as the API grows.
Inside this chapter
- Good Naming Principles
- Examples of Better and Worse Paths
- Nested Resources
- Versioning Strategies
- Enterprise Example
Series navigation
Study the chapters in order for the clearest path from REST basics to advanced API design, operations, and production readiness. Use the navigation at the bottom to move smoothly across the full tutorial series.
Good Naming Principles
Good API endpoint names are simple, consistent, and resource-oriented. Most REST APIs use lowercase paths, plural resource names, and predictable nested structures where relationships matter.
Examples of Better and Worse Paths
Good:
/users
/users/42
/orders/1001/items
Less ideal:
/getUserById
/createNewOrderNow
/allUserOrderItemsListNested Resources
Nested paths can express relationships clearly, but too much nesting can make APIs hard to use. For example, /customers/5/orders is reasonable, but very deep paths may signal that the data model needs a cleaner access pattern.
Versioning Strategies
/api/v1/users
/api/v2/usersVersioning helps APIs evolve without breaking older clients. Path-based versioning is common, though header-based approaches also exist. The key is to introduce change deliberately and document it clearly.
Enterprise Example
A logistics company may have separate versions of shipment APIs for older handheld devices and newer partner integrations. Clear endpoint naming and version strategy prevent operational confusion at scale.