During a recent sharing session with our CTO, Brian de Heus, we talked about REST API design. One point that stayed with me was his opinion on nested API endpoints. He argued that nested endpoints are a bad idea.

Because time was limited, we did not get much extra context in that session, so I wanted to expand on the topic here and explain why nested endpoints often become problematic.

What Is a Nested API Endpoint?

A nested API endpoint is an endpoint where one resource is placed under another resource in the URL. The idea is to reflect a hierarchy between resources.

# Simple endpoint
/api/v1/users/123

# Nested endpoints
/api/v1/users/123/tasks/456
/api/v1/teams/789/users/123/tasks/456

Perceived Benefits

At first glance, nested endpoints seem attractive for a few reasons.

1. Clear Resource Hierarchy

  • They explicitly show ownership relationships
  • The URL reflects your data structure
  • They make containment feel obvious

2. Intuitive Navigation

  • The paths feel natural to read
  • They mirror how we often think about relationships
  • They appear to make the API easier to explore

3. Apparent Simplicity

  • They match how we often visualize related data
  • They seem close to how database queries are structured
  • They appear to encode business rules directly in the URL

The problem is that these benefits are often superficial. In practice, nested endpoints usually create more trouble than value.

The Major Challenges

1. Path Ambiguity and Redundancy

One of the biggest problems is that the same resource can end up being accessible through multiple valid paths. For example:

/api/v1/tasks/456
/api/v1/users/123/tasks/456
/api/v1/teams/789/users/123/tasks/456

That immediately raises important questions:

  • Consistency: do all of these endpoints return exactly the same data?
  • Best practices: which one should developers actually use?
  • Maintenance: how do you guarantee consistent behavior across all paths?
  • Documentation: how do you document multiple ways to access the same resource without creating confusion?

2. Inconsistent Depth Problems

Now imagine a deeper structure like this:

/api/v1/companies/1/departments/2/employees/3/tasks/4/comments/5

This creates a new set of architectural questions:

  • Access patterns: should the resource be accessible from every level?
/api/v1/comments/5
/api/v1/tasks/4/comments/5
/api/v1/employees/3/comments/5
  • Consistency rules: what makes a path valid?
  • Performance: how do you efficiently validate the whole chain?
  • Caching: how do you cache responses when the same resource can appear under many URLs?

3. Permission and Authorization Complexity

Nested endpoints also make access control more confusing:

/api/v1/users/123/posts/456        # Requires user ownership?
/api/v1/posts/456                  # Just needs authentication?
/api/v1/teams/789/posts/456        # Demands team membership?

This creates several security concerns:

  • Permission inheritance: should access rights flow through the hierarchy?
  • Authorization logic: how do you keep authorization rules consistent across different paths?
  • Security auditing: how do you verify that every possible path is properly protected?

4. Resource Relationship Confusion

In real systems, a resource often belongs to more than one parent. That makes the "correct" path unclear:

/api/v1/users/123/posts/456        # Post by user perspective
/api/v1/categories/789/posts/456   # Post by category perspective
/api/v1/teams/567/posts/456        # Post by team perspective

That leads to more design problems:

  • Canonical URLs: which path should be treated as the official one?
  • Data consistency: how do you guarantee the same representation across multiple paths?
  • API evolution: what happens when new relationships are added later?

A Better Approach

1. Flat Resources with Query Parameters

/api/v1/tasks?user_id=123&team_id=789
/api/v1/tasks/456

2. Resource Expansion Parameters

/api/v1/tasks/456?expand=user,team,comments

3. Separate Relationship Endpoints

/api/v1/users/123/task-assignments

Benefits of a Flat Design

  • Simplicity: one resource, one endpoint
  • Clear permissions: easier to implement and reason about
  • Better caching: cleaner and more predictable URL patterns
  • Flexible querying: relationships and filtering can move into query parameters
  • Easier evolution: new relationships can be added without redesigning the whole URL structure

Conclusion

Nested API endpoints may feel intuitive at first, but they often introduce more problems than they solve. The apparent clarity of hierarchical URLs is usually outweighed by ambiguity, permission complexity, and long-term maintenance costs.

When designing an API:

  • Prefer flat resource endpoints
  • Use query parameters for filtering and relationships
  • Think about long-term maintainability
  • Favor clarity and consistency over strict hierarchical representation

The goal of API design is not just to make something easy to read today. It is to build interfaces that remain understandable, maintainable, secure, and adaptable over time.