Example of implementation

Example using Resource loader API

This guide provides a practical use case example for implementing the Feature Experimentation Resource Loader API. It demonstrates how to create a complete feature flag campaign with variations, targeting rules, and goals using a single API call.

Overview

The Resource Loader API allows you to create, update, or delete multiple related resources (projects, campaigns, flags, goals, targeting keys, variation groups, and variations) in a single HTTP POST request. This approach ensures data consistency and simplifies the creation of complex feature experimentation setups.

API Endpoint

POST https://resource-loader-api.abtasty.com/v1/feature-exp/resource-loader

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN (Remote Control API)

Use Case Example: Creating a Feature Flag A/B Test

This example demonstrates creating a complete feature experimentation setup that includes:

• A project to organize campaigns

• Feature flags for controlling features

• Targeting keys for audience segmentation

• Goals for conversion tracking

• An A/B test campaign with multiple variations

• Variation groups with targeting rules

Complete Resource Loader Payload

{
  "version": 1,
  "resources": [
    {
      "type": "project",
      "$_ref": "mobile_app_project",
      "action": "create",
      "payload": {
        "name": "Mobile App - Summer 2026"
      }
    },
    {
      "type": "flag",
      "$_ref": "button_color_flag",
      "action": "create",
      "payload": {
        "name": "primary_button_color",
        "type": "string",
        "description": "Color variant for primary CTA buttons",
        "source": "manual"
      }
    },
    {
      "type": "targeting-key",
      "$_ref": "user_segment_key",
      "action": "create",
      "payload": {
        "type": "string",
        "name": "user_segment",
        "description": "User segment classification (premium, standard, free)"
      }
    },
    {
      "type": "goal",
      "$_ref": "add_to_cart_goal",
      "action": "create",
      "payload": {
        "type": "screenview",
        "label": "add_to_cart",
        "operator": "contains",
        "value": "product_added_to_cart"
      }
    },
    {
      "type": "campaign",
      "$_ref": "button_color_test",
      "action": "create",
      "payload": {
        "project_id": "$mobile_app_project.id",
        "name": "CTA Button Color Optimization",
        "description": "Multi-variant test for button color conversion",
        "type": "ab",
        "variation_groups": [
          {
            "name": "All Standard Users",
            "variations": [
              {
                "name": "Control - Blue Button",
                "reference": true,
                "allocation": 25
              },
              {
                "name": "Variant A - Green Button",
                "reference": false,
                "allocation": 25,
                "modifications": {
                  "type": "FLAG",
                  "value": {
                    "primary_button_color": "green"
                  }
                }
              },
              {
                "name": "Variant B - Orange Button",
                "reference": false,
                "allocation": 25,
                "modifications": {
                  "type": "FLAG",
                  "value": {
                    "primary_button_color": "orange"
                  }
                }
              },
              {
                "name": "Variant C - Red Button",
                "reference": false,
                "allocation": 25,
                "modifications": {
                  "type": "FLAG",
                  "value": {
                    "primary_button_color": "red"
                  }
                }
              }
            ],
            "targeting": {
              "targeting_groups": [
                {
                  "targetings": [
                    {
                      "operator": "EQUALS",
                      "key": "user_segment",
                      "value": "standard"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Step-by-Step Implementation

Step 1: Prepare Your Payload

Create a JSON file (e.g., feature-campaign-setup.json) with your resource loader configuration. Use the $_ref notation to reference resources created earlier in the same request.

Step 2: Make the API Request

Using cURL

curl -X POST https://resource-loader-api.abtasty.com/v1/feature-exp/resource-loader?account_id=<account_id>&account_environment_id=<account_environment_id>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d @feature-campaign-setup.json

Using JavaScript (Fetch API)

const resourceLoaderPayload = {
  version: 1,
  resources: [
    // Your resources here
  ],
};

fetch(
  "https://resource-loader-api.abtasty.com/v1/feature-exp/resource-loader?account_id=12345&account_environment_id=67890",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_API_TOKEN",
    },
    body: JSON.stringify(resourceLoaderPayload),
  }
)
  .then((response) => response.json())
  .then((data) => {
    console.log("Success:", data);
  })
  .catch((error) => {
    console.error("Error:", error);
  });

Step 3: Handle the Response

The API will return a response containing the IDs of all created resources:

{
  "status": "success",
  "results": [
    {
      "$_ref": "mobile_app_project",
      "status": "success",
      "response": {
        "id": "prj_abc123xyz",
        "name": "Mobile App - Summer 2026"
      }
    },
    {
      "$_ref": "button_color_flag",
      "status": "success",
      "response": {
        "id": "flg_jkl012mno"
      }
    }
    // Additional results for campaign and variation...
  ]
}

Advanced Use Cases

Updating Existing Resources

To update an existing campaign, use the edit action and provide the resource ID:

{
  "version": 1,
  "resources": [
    {
      "type": "campaign",
      "$_ref": "update_campaign",
      "action": "edit",
      "payload": {
        "id": "cmp_zab123cde",
        "name": "Checkout Redesign - Premium Users (Updated)",
        "description": "Updated campaign description with new insights"
      }
    }
  ]
}

Deleting Resources

To delete a resource:

{
  "version": 1,
  "resources": [
    {
      "type": "goal",
      "$_ref": "delete_goal",
      "action": "delete",
      "payload": {
        "id": "gol_hij234klm"
      }
    }
  ]
}

Using Reference Injection

You can inject existing resource IDs from command-line flags when using the AB Tasty CLI:

abtasty feature-experimentation resource load \
  --file feature-campaign-setup.json \
  --input-ref '{"existing_project":"prj_abc123xyz"}'

Then reference them in your JSON:

{
  "type": "campaign",
  "payload": {
    "project_id": "$existing_project",
    "variation_groups": [
      {
        "variations": [
          {
            "modifications": {
              "type": "FLAG",
              "value": {
                "enable_new_checkout": true
              }
            }
          }
        ]
      }
    ]
  }
}

Key Concepts

1. Reference System ($_ref)

Each resource uses a unique reference identifier that can be used to link resources within the same request:

{
  "type": "project",
  "$_ref": "my_project",
  "action": "create"
}

// Later in the same request
{
  "type": "campaign",
  "payload": {
    "project_id": "$my_project.id"
  }
}

2. Variation Groups and Targeting

Variation groups define how users are segmented and which variations they see:

"variation_groups": [
  {
    "name": "Premium Users",
    "variations": [...],
    "targeting": {
      "targeting_groups": [
        {
          "targetings": [
            {
              "operator": "EQUALS",
              "key": "user_segment",
              "value": "premium"
            }
          ]
        }
      ]
    }
  }
]

3. Flag Modifications

Variations modify feature flag values to deliver different experiences:

"modifications": {
  "type": "FLAG",
  "value": {
    "enable_new_checkout": true,
    "primary_button_color": "green"
  }
}

4. Traffic Allocation

Allocations must sum to 100% within each variation group:

"variations": [
  {
    "name": "Control",
    "allocation": 50
  },
  {
    "name": "Variant A",
    "allocation": 50
  }
]

Targeting Operators

Use these operators in your targeting rules:

Operator	Description	Example
EQUALS	Exact match	"value": "premium"
IN	In	"value": "free"
CONTAINS	Contains substring	"value": "prod"

Flag Types

Feature flags support multiple data types:

Type	Description	Example Value
boolean	True/false values	true, false
string	Text values	"green", "v2"
number	Numeric values	42, 3.14

Goal Types

Track different conversion events:

Type	Description	Use Case
screenview	Screen/page views	Track navigation
event	Custom events	Button clicks, interactions
transaction	Purchase events	E-commerce conversions

Best Practices

1. Use Meaningful References: Choose descriptive $_ref names that clearly indicate what each resource represents (e.g., premium_users_campaign instead of c1).

2. Define Dependencies First: Create projects, flags, and targeting keys before campaigns that use them.

3. Validate Allocations: Always ensure variation allocations sum to exactly 100% within each variation group.

4. Start with Paused Campaigns: Create campaigns in a paused state, then activate after verification.

5. Test Targeting Rules: Verify targeting logic with test users before full deployment.

6. Use Descriptive Names: Give clear names to variations that describe what they're testing (e.g., "New Checkout Flow" not "Variant A").

7. Document Flag Values: Include descriptions for all flags explaining their purpose and expected values.

8. Handle Errors Gracefully: Check the response status for each resource and implement retry logic for transient failures.

9. Version Your Payloads: Keep your resource loader JSON files in version control to track changes over time.

10. Monitor Flag Usage: Track which flags are actively used in campaigns before deleting them.

Support

For questions or issues with the Resource Loader API, consult the main Resource Loader documentation or contact AB Tasty support.