What’s the best REST approach for handling path-based resource naming with hierarchical structures? How can I avoid these ambiguities while keeping the API clean and intuitive?
I’ve hit this exact issue before. Query parameters work way better than trying to embed the path structure in the URL. Instead of making your API guess where the resource name ends and the action starts, try something like: https://api.mysite.com/workspaces?path=/team/department/workspacename and https://api.mysite.com/workspaces/files/report.pdf?workspace_path=/team/department/workspacename. This kills the ambiguity completely - the hierarchical structure is separate from your resource operations. You keep clean URLs but dodge the parsing nightmare. The path parameter handles any depth without breaking your routing, and it’s way easier to validate on the backend. I tried path encoding and custom delimiters too, but query parameters were the most reliable in production.
you could also use encoded paths with a special delimiter. Something like https://api.mysite.com/workspaces/teamA~deptB~myworkspace/files/report.pdf where ~ separates path segments. you can decode the hierarchy while keeping clear boundaries between resources and actions. We’ve used this pattern succesfully - just make sure your delimiter can’t appear in actual names.
Use resource IDs in your URLs instead of hierarchical paths. Set up endpoints like https://api.mysite.com/workspaces/{workspace_id}/files/{file_id} where workspace_id is a unique identifier that maps to your full path structure. Store the path hierarchy in your database and resolve it server-side. This kills URL ambiguity completely since each resource gets a distinct ID no matter where it sits in the hierarchy. You can still do path-based lookups with additional endpoints like https://api.mysite.com/workspaces/resolve?path=/team/dept/workspace that returns the workspace ID, then use that ID for everything else. This keeps your API RESTful without the headache of parsing variable-depth paths.