Link Resources with References

Connect your resources and fetch related data in one API call. Use reference fields to link articles to authors, products to categories, or any resources that belong together — then retrieve them with the populate parameter.

What are Reference Fields?

Reference fields create associations between resources in different collections:

• Reference — Links to a single resource in another collection
• Relation — Links to multiple resources in another collection

Common use cases include:

• Author field on articles pointing to a Users collection
• Category field on products pointing to a Categories collection
• Related articles linking to other articles in the same collection

Prerequisites

Before creating reference fields, you need:

• Two collections — one to hold the reference field, another as the target
• At least one published resource in the target collection
• Appropriate permissions to modify schemas in the target environment

Step 1 – Create the Target Collection

First, create the collection that will be referenced. For this example, we'll create a Users collection:

1. Open your environment in the FoxNose dashboard.
2. Click Database in the sidebar.
3. Click Add collection and configure:

4. Add fields to the schema (e.g., name, nickname).
5. Click Publish version to activate the schema.
6. Add at least one resource to the Users collection.

Step 2 – Add Reference Field to Source Collection

Now add a reference field to the collection that will link to Users:

1. Navigate to the source collection (e.g., Comments).
2. Switch to the Schema tab.
3. Click Add field and select Reference as the field type.
4. Configure the reference field:

5. Click Add field to add the reference.
6. Click Publish version to apply the schema changes.

Step 3 – Set Reference Values

When editing a resource with a reference field:

1. Navigate to the source collection and open a resource.
2. Find the reference field (e.g., Author).
3. Use the dropdown to search and select a resource from the target collection.
4. Save and publish the resource.

The reference stores the target resource's key internally (e.g., b5qarwj6we70).

Step 4 – Connect Collections to Flux API

For the populate feature to work, both collections must be connected to your Flux API:

1. Go to Delivery → Flux API in the sidebar.
2. Select your API.
3. In the Connected Collections tab, ensure both the source collection (Comments) and target collection (Users) are connected.
4. Enable both List/Search and Get Resource access methods for each collection.

Step 5 – Use Populate in API Requests

By default, reference fields return only the target resource's key:

GET /content/articles/{article_key}/comments

{
  "results": [
    {
      "_sys": { "key": "6en834phv3uj", "folder": "comments" },
      "data": {
        "body": "Great article!",
        "author": "b5qarwj6we70"
      }
    }
  ]
}

Add populate=author to expand the reference into the full object:

GET /content/articles/{article_key}/comments?populate=author

{
  "results": [
    {
      "_sys": { "key": "6en834phv3uj", "folder": "comments" },
      "data": {
        "body": "Great article!",
        "author": {
          "name": "Alice Johnson",
          "nickname": "alice_j"
        }
      }
    }
  ]
}

Populate Multiple Fields

Populate multiple reference fields by separating them with commas:

GET /content/articles?populate=author,category

Nested Population

Populate nested references using dot notation (up to 3 levels deep):

GET /content/articles?populate=author.company,category.parent

This expands:

• The author reference, then the author's company reference
• The category reference, then the category's parent reference

Population Limits

Reference vs Strict Reference

Choose Reference when:

• Resources can exist without each other
• You need many-to-many relationships
• Resources are managed independently

Choose Strict Reference when:

• Child has no meaning without parent
• You want nested URL structure
• Child lifecycle depends on parent

Best Practices

• Connect all referenced collections to your Flux API before using populate
• Use specific populate paths — only request fields you need to minimize response size
• Consider response size — deeply nested population can create large responses
• Cache populated responses — they require additional database lookups

Next Step

References work great for associations where both sides can exist independently. But what about true ownership — where a child resource has no meaning without its parent? Comments belong to articles. Order items belong to orders.