Resource Loader

Definition, advantages

Overview of the Concept

We’re adopting a uniform, plain-text template to document each resource in our JSON “resource loader.” By clearly laying out the type, supported actions, parent relationship, payload fields, response format, and error codes for every resource, we give developers a single, easy-to-scan reference. This saves time compared to hunting through multiple API docs or experimenting with endpoints. More importantly, when bundling numerous operations (campaign → variation → modification) into one nested request via the resource loader. In this “resource loader” JSON:

• Each item in a top‐level resources: [...] array describes one operation.

• The common fields (type, $_ref, $_parent_id, action, payload) let the client declare what to do (e.g., “create a new campaign”), assign a local reference ($_ref: “c1”), and then refer to that newly created ID later in the same batch (e.g., “$_parent_id”: “$c1.id”).

• By introducing a resources array inside each resource node, we allow clients to group child operations directly under their parent, rather than listing everything flatly. Below is a concise breakdown:

At a high level, this can be thought of as a mini-transaction or bulk API where the client submits a directed graph of operations, and the CLI executes them in dependency order.

Advantages of This Approach

1. Visual & Logical Clarity

   Readers immediately see “these variations belong to this campaign” and “these modifications belong to that variation”.

2. Guaranteed Parent-Before-Child Processing

   A simple depth-first traversal (parent, then children, then grandchildren) automatically ensures that, for example, a variation is never created before its campaign.

3. Single Authorization Flow

   Instead of creating a session or OAuth token for each separate call, the CLI can validate the user’s permissions once for the entire batch.

4. Consistency Checking

   On the application side, we can validate the entire graph for referential integrity before it hits the API.

5. Simplified Client Logic

   The client needs only one place in code to handle “send resources array,” observes one combined response, and then pulls out IDs from each $_ref.

6. Simplified Error Reporting

   Because each node can carry its own $_ref, the server’s response can pinpoint exactly which node failed or succeeded. If a modification under variation “v1” fails, we know precisely which subtree was affected.

7. Inject reference value using the command flag

   The $_ref property is dynamic and can be generated within the JSON after the resource variable or injected from the command line flag “--input-ref” as an object to be referred to inside the JSON

When to Use—and When to Reconsider—This Pattern

• Ideal Scenarios

  1. Hierarchical Creation is Common: We frequently see clients needing to create an entire tree (campaign → variation → modification) in one workflow.

  2. Strong Referential Integrity: We want to guarantee that no variation exists without a campaign, and no modification exists without its variation.

• When to Reconsider

  1. Complex Business Logic Per Resource: If, for instance, creating a modification sometimes involves an external call that can fail unpredictably, wrapping everything in a single request might block the entire batch. In that case, we might prefer separate calls with local retries.

  2. Security/Permission Granularity: If different resources require different OAuth scopes—e.g., we need a “campaign:create” scope for campaigns, a “variation:update” scope for variations—the CLI needs to carefully inspect each item’s credentials.

Links:

• Web Experimentation

• Feature Experimentation & Rollout - Coming Soon