RESTful API嵌套资源直接访问最佳实践与层级资源访问规则咨询

Context #

I'm building a Web API to manage two-tier hierarchical objects (Group → SubGroup) with these core rules:

• Groups are added only by name, which serves as their business unique identifier
• SubGroups are added only by name, with groupName + subGroupName as their business unique identifier
• SubGroups can only exist within the context of a parent Group
• Both Groups and SubGroups have system-generated unique IDs (separate from their names)

I need to implement an endpoint to query a specific SubGroup's details, but I'm unsure whether to provide direct access to this resource. I've looked through related threads without a clear answer, and have two options:

• Option 1: Endpoint requiring both group name and sub-group name: /groups/subgroups?groupName="x"&subGroupName="y"
• Option 2: Endpoint using the SubGroup's internal unique ID (returned on creation): /subgroups?id="52regfd235fdsf325f"

Questions #

1. What's the best practice for this scenario? Is a direct access endpoint for nested resources acceptable? Should the SubGroup deletion endpoint use the ID or the name combination?
2. What are the experience rules for accessing the final tier resource in a general hierarchical structure like H1→H2→H3→...→Hn?

My Answer #

Great question—this is a super common design dilemma when building hierarchical REST APIs, and while there’s no universal "right" answer, we can break down the best practices based on your use case and standard REST principles.

1. Best Practices for Your Two-Tier Scenario #

First off: both endpoint patterns are valid, but the right choice depends on who’s using your API and how they’ll interact with it. Consistency across your API is key.

SubGroup Query Endpoints

• If your API is primarily used by folks who work with business identifiers (like operations teams, or client apps that tie directly to business data), Option 1 makes sense—but I’d tweak it to use path parameters instead of query params for better REST compliance: GET /groups/{groupName}/subgroups/{subGroupName}. This structure mirrors the hierarchical relationship directly, and users don’t have to juggle internal IDs they don’t care about.
• If your API is used more by technical systems (like service-to-service calls, or apps that need stable, efficient resource lookup), or if there’s any chance SubGroup or Group names might change down the line, Option 2 (with a cleaner path: GET /subgroups/{subGroupId}) is the way to go. Internal IDs are immutable, so they provide a stable target for calls even if business names shift.

Pro tip: You can absolutely support both endpoints. The nested path serves business use cases, while the direct ID endpoint serves technical ones—just make sure both return the exact same resource data to avoid confusion.

SubGroup Deletion Endpoint

The golden rule here is use the most stable identifier available:

• If you’re 100% certain group and subgroup names will never change, DELETE /groups/{groupName}/subgroups/{subGroupName} works fine and keeps the operation tied to the business context.
• But if there’s even a remote possibility of name changes (or if you want future-proofing), prioritize the internal ID: DELETE /subgroups/{subGroupId}. Internal IDs don’t depend on business logic changes, so they eliminate the risk of failed deletions due to renamed resources.

And to answer your question directly: Yes, direct access endpoints for nested resources are totally acceptable. REST doesn’t require you to traverse parent resources to reach child ones—if a resource has its own unique identity (which your SubGroup does, thanks to the internal ID), it deserves its own root endpoint.

2. Experience Rules for N-Tier Hierarchical Resources #

For deeper hierarchies (H1→H2→...→Hn), here are the go-to guidelines I follow:

• Treat leaf resources as independent entities: If the final tier (Hn) has its own unique ID and lifecycle, give it a root endpoint like /hn-resources/{hnId}. This lets users access it directly without traversing the entire hierarchy every time.
• Keep context paths as an option: Maintain the full hierarchical path (like /h1/{h1Id}/h2/{h2Id}/.../hn/{hnId}) for cases where users need to access the resource within the context of its parent hierarchy (e.g., "get all H3s under this H1").
• Avoid overly deep paths: Once you get past 3-4 tiers, long paths become unwieldy. Instead, simplify with query params: GET /hn-resources?h1Id=xxx&h2Id=xxx or keep the first couple of tiers in the path and use params for the rest.
• Prioritize internal IDs over business identifiers: For deep hierarchies, combining business names across tiers gets messy fast (think /regions/{regionName}/countries/{countryName}/cities/{cityName}/neighborhoods/{neighborhoodName}). Internal IDs are shorter, more stable, and easier to work with in code.
• Be consistent: Whatever rules you set for one tier, apply them to all. If H2 can be accessed directly, H3 and Hn should too—don’t mix and match patterns randomly, as that confuses API users.

内容的提问来源于stack exchange，提问作者sborpo