REST Lens

Category: URI Structure

Description

URI paths should follow hierarchical design principles, using path parameters for hierarchical relationships and structuring paths in a logical top-down manner.

What It Checks

This rule validates proper hierarchical URI design:

Hierarchical elements in paths: Query parameters shouldn't be used for hierarchical relationships
Top-down structure: Path hierarchies should follow logical parent-child relationships
Consistent nesting: Related resources should use nested paths

Why It Matters

Proper hierarchy design improves API usability:

Clarity: Relationships between resources are immediately obvious
Discoverability: Developers can predict related endpoint structures
RESTful design: Follows REST principles for resource relationships
Caching: Hierarchical URLs work better with HTTP caching

Examples

Good ✅

paths:
  # Hierarchical path parameters
  /organizations/{orgId}/projects/{projectId}:
    get:
      summary: Get a project within an organization

  # Nested resources
  /users/{userId}/orders:
    get:
      summary: Get orders for a specific user

  # Clear parent-child relationship
  /stores/{storeId}/products/{productId}/reviews:
    get:
      summary: Get reviews for a product in a store

Bad ❌

paths:
  # Using query param for hierarchical relationship
  /projects:
    get:
      parameters:
        - name: orgId  # ❌ Should be in path
          in: query

  # Flat structure for related resources
  /orders:
    get:
      parameters:
        - name: userId  # ❌ Should be /users/{userId}/orders
          in: query

  # Illogical hierarchy
  /reviews/{reviewId}/products/{productId}:  # ❌ Backwards hierarchy
    get:
      summary: Should be /products/{productId}/reviews/{reviewId}

Hierarchy Validation Rules

1. Use Path Parameters for Hierarchical Elements

Bad: Query parameters for parent resources

GET /projects?organizationId=123

Good: Path parameters show hierarchy

GET /organizations/123/projects

2. Structure Paths Top-Down

Bad: Child before parent

/comments/{commentId}/posts/{postId}  # Comments belong to posts

Good: Parent before child

/posts/{postId}/comments/{commentId}

3. Use Nested Paths for Related Resources

Bad: Flat structure with filter

GET /orders?customerId=456
GET /orders?storeId=789

Good: Nested structure showing relationship

GET /customers/456/orders
GET /stores/789/orders

Configuration

This rule has no configuration options.

Common Patterns

Organization → Project → Resource

/organizations/{orgId}/projects/{projectId}/resources/{resourceId}

User → Content

/users/{userId}/posts
/users/{userId}/comments
/users/{userId}/likes

Store → Products → Details

/stores/{storeId}/products
/stores/{storeId}/products/{productId}
/stores/{storeId}/products/{productId}/inventory

How to Fix

Move hierarchical filters to path:

# Before
GET /projects?orgId=123

# After
GET /organizations/123/projects

Reverse illogical hierarchies:

# Before
/reviews/{reviewId}/products/{productId}

# After
/products/{productId}/reviews/{reviewId}

Use nested paths for relationships:

# Before
GET /comments?postId=456

# After
GET /posts/456/comments

Exceptions

Query parameters ARE appropriate for:

Filtering: /products?category=electronics&inStock=true
Sorting: /users?sort=createdAt&order=desc
Pagination: /orders?page=2&limit=20
Search: /products?q=laptop

These are NOT hierarchical relationships—they're operations on the collection.

Related Rules

Rule 71: Query Filter Collection - Proper use of query params
Rule 23: Query Fields GET - Field selection via query params

Hierarchy Design