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 folders:

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

Common use cases include:

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

Prerequisites

Before creating reference fields, you need:

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

Step 1 – Create the Target Folder

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

1. Open your environment in the FoxNose dashboard.
2. Click Database in the sidebar.
3. Click Add folder 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 folder.

Step 2 – Add Reference Field to Source Folder

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

1. Navigate to the source folder (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 folder 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 folder.
4. Save and publish the resource.

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

Step 4 – Connect Folders to Flux API

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

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

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 folders 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.