# Resource Loader

### **Overview of the Concept** <a href="#id-3.-advantages-of-this-approach" id="id-3.-advantages-of-this-approach"></a>

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 <a href="#id-3.-advantages-of-this-approach" id="id-3.-advantages-of-this-approach"></a>

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 <a href="#id-8.-when-to-use-and-when-to-reconsider-this-pattern" id="id-8.-when-to-use-and-when-to-reconsider-this-pattern"></a>

* **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](/server-side/command-line-interface/resource-loader/web-experimentation.md)
* [Feature Experimentation & Rollout](/server-side/command-line-interface/resource-loader/feature-experimentation.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.abtasty.com/server-side/command-line-interface/resource-loader.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.