Relationship Expansion

Basic Relationship Expansion

By default, api.vision includes foreign keys in responses but doesn't expand related resources. To include related resources, use the expand query parameter:

GET /posts?expand=author

This returns posts with the author relation expanded, including all fields from the author resource.

Response Format

Here's an example of a response with expanded relationships:

// Without expansion: GET /posts

[
  {
    "id": 1,
    "title": "Getting Started with API Design",
    "content": "...",
    "authorId": 42,
    "createdAt": "2023-04-15T14:32:10Z"
  }
]

// With expansion: GET /posts?expand=author

[
  {
    "id": 1,
    "title": "Getting Started with API Design",
    "content": "...",
    "authorId": 42,
    "createdAt": "2023-04-15T14:32:10Z",
    "author": {
      "id": 42,
      "username": "techguru",
      "name": "Alex Chen",
      "email": "alex@example.com",
      "role": "admin"
    }
  }
]

Expanding Multiple Relationships

You can expand multiple relationships by providing a comma-separated list:

GET /posts?expand=author,comments

This expands both the author and comments relationships for each post.

Nested Relationship Expansion

You can expand nested relationships using dot notation:

GET /posts?expand=comments.author

This expands the comments relationship for each post, and also expands the author relationship for each comment.

You can combine multiple nested expansions:

GET /posts?expand=author,comments.author,comments.likes

This example:

• Expands the author of each post
• Expands the comments for each post
• For each comment, expands the author and likes

Selective Expansion

When expanding relationships, you can select specific fields to include from the related resources using the fields parameter:

GET /posts?expand=author&fields=id,title,content,author.id,author.name

This returns the id, title, and content fields from posts, and only the id and name fields from the expanded author.

Collection Expansions

When expanding a one-to-many or many-to-many relationship, the result is an array of related resources:

// GET /posts/1?expand=comments

{
  "id": 1,
  "title": "Getting Started with API Design",
  "content": "...",
  "authorId": 42,
  "createdAt": "2023-04-15T14:32:10Z",
  "comments": [
    {
      "id": 101,
      "postId": 1,
      "authorId": 24,
      "text": "Great article!",
      "createdAt": "2023-04-15T15:10:22Z"
    },
    {
      "id": 102,
      "postId": 1,
      "authorId": 35,
      "text": "Very helpful, thanks!",
      "createdAt": "2023-04-15T16:45:37Z"
    }
  ]
}

Filtering Expanded Collections

You can filter the expanded collections using dot notation in your filter parameters:

GET /posts/1?expand=comments&comments.createdAt_gte=2023-04-15T16:00:00Z

This expands only comments created after the specified time.

Sorting Expanded Collections

You can sort expanded collections using dot notation in your sort parameter:

GET /posts/1?expand=comments&sort=comments.createdAt

This sorts the expanded comments by their creation date (oldest first).

Pagination for Expanded Collections

You can paginate expanded collections using dot notation:

GET /posts/1?expand=comments&comments.page=1&comments.limit=5

This returns only the first 5 comments in the expanded collection. The response includes pagination metadata for the expanded collection.

Expansion Depth Limit

To prevent performance issues with deeply nested expansions, api.vision has a default depth limit:

• Default max depth: 3 levels
• You can override this using the maxDepth parameter: ?expand=a.b.c.d&maxDepth=4
• Server administrators can set hard limits that cannot be exceeded

Performance Considerations

While relationship expansion is powerful, it comes with performance considerations:

• Response Size: Expansions can dramatically increase response payload size
• Query Complexity: Each expansion may require additional database queries
• Server Load: Excessive expansions can increase server load

Best practices for efficient expansions:

• Expand only what you need for your current view or operation
• Combine expansion with field selection to limit the fields included
• Use pagination for large collections
• Consider separate requests for deeply nested data

Advanced Example

GET /posts?
  fields=id,title,author.name,comments.text,comments.author.name&
  expand=author,comments.author&
  comments.page=1&
  comments.limit=3&
  sort=-createdAt&
  comments.sort=-createdAt

This complex example:

• Returns posts sorted by creation date (newest first)
• Includes only id and title fields from posts
• Expands the author relationship, including only the name field
• Expands the comments relationship, including only text field
• For each comment, expands the author relationship, including only the name field
• Limits comments to the 3 most recent ones per post
• Sorts comments by creation date (newest first)