5-minute tour

One command, one endpoint, and Reqloom works out the six requests that have to happen first. This tour shows that on the bundled sample.

You need: Reqloom installed (download) and about five minutes. No backend and no configuration.

Get the sample

The sample project lives in the repository:

git clone https://github.com/Mirzabaig313/Reqloom
cd Reqloom/samples/marketplace

• Directorysamples/marketplace/

  • reqloom.yaml project root + imports
  • Directoryenvironments/

    • local.yaml baseUrl, test users, !secret passwords
  • Directoryactors/

    • admin.yaml email + password
    • vendor.yaml email + password, with token refresh
    • customer.yaml phone + OTP, a two-step chain
  • Directoryresources/

    • products.yaml 7 operations
    • cart.yaml 4 operations
    • orders.yaml 7 operations
    • refunds.yaml 5 operations
    • reviews.yaml 4 operations

1. Check that it parses

   reqloom lint

   LINT OK — 3 actors, 5 resources, 27 operations. No errors.

   lint sends no requests. It parses every file, resolves every {{...}} reference, and dry-runs all 27 operations to prove each one’s chain can be ordered. Those counts are also the quickest way to confirm the parser sees what you expect.

2. Look at what you’re about to run

   refund.approve is the last step of a refund flow. Here is its entire declaration:

   resources/refunds.yaml

   approve:
     method: POST
     path: /api/v1/admin/refunds/{{refund.refund_id}}/approve
     actor: admin
     depends_on: [refund.request]
     expect_status: 200

   One dependency. Note the two things it says: it runs as admin, and it needs a refund to exist.

3. Run it

   reqloom run refund.approve

   Loaded project: MarketplaceAPI (3 actors, 5 resources)
   Running: refund.approve (chain of 7 steps, env=local)
     [1] Running: product.create (attempt 1)
     [2] Running: product.publish (attempt 1)
     [3] Running: cart.add_item (attempt 1)
     [4] Running: order.create (attempt 1)
     [5] Running: order.pay (attempt 1)
     [6] Running: refund.request (attempt 1)
     [7] Running: refund.approve (attempt 1)
   
   Result: SUCCEEDED

   That’s the whole point of the tool. You asked for one operation and got seven, in dependency order, across three different logged-in identities — from a schema that declared one edge per file.

4. See where the chain came from

   Follow the declarations backwards and the seven steps are just one edge each:

   | Step | Needs | Why | | --- | --- | --- | | refund.approve | refund.request | can’t approve a refund that doesn’t exist | | refund.request | order.pay | can’t refund an unpaid order | | order.pay | order.create | can’t pay a nonexistent order | | order.create | cart.add_item | can’t order an empty cart | | cart.add_item | product.publish | can’t buy an unpublished product | | product.publish | product.create | can’t publish nothing |

   Nobody wrote that list. It falls out of the graph, and it re-derives itself when you change the schema.

5. Notice what isn’t in the output

   Three actors took part — vendor for steps 1–2, customer for 3–6, admin for step 7 — so three logins happened. None of them appear as steps.

   A login is part of whichever step needs it, and the session is cached for its TTL, so seven steps across three identities cost three logins rather than seven. You never see a token, and you never copy one.

Running it for real

The sample points at http://localhost:3000, and the repository ships no backend — so on a fresh clone the requests have nowhere to go. What you’ll actually see is the chain resolving correctly and then failing at the network:

Running: refund.approve (chain of 7 steps, env=local)
  [1] Running: product.create (attempt 1)
  [1] FAILED: product.create [E_SESSION_REFRESH_FAILED] —

Result: FAILED

--- Chain Summary ---
Target: refund.approve   Env: local   Outcome: FAILED
  FAIL   product.create (0ms) err=E_SESSION_REFRESH_FAILED
  BLOCK  product.publish (0ms) err=—
  BLOCK  cart.add_item (0ms) err=—
  BLOCK  order.create (0ms) err=—
  BLOCK  order.pay (0ms) err=—
  BLOCK  refund.request (0ms) err=—
  BLOCK  refund.approve (0ms) err=—

This is worth reading rather than skipping. The chain still resolved to the same seven steps — resolution is independent of whether the API answers. Step 1 failed because the vendor’s login couldn’t reach the server, and the other six are BLOCK: never attempted, because something upstream failed. That’s your signal to fix the first failure rather than debug seven things.

Make offline failures fast

Each step retries 3 times, and each attempt waits out the 5s connect timeout, so a dead host takes minutes. While experimenting, cut it:

environments/local.yaml

transport:
  connect_timeout: 100ms

To get the green run, point baseUrl at an API implementing these routes:

reqloom run refund.approve --var baseUrl=https://your-api.example.com

Or edit environments/local.yaml. The passwords are !secret entries, so add those to your keychain first — see secrets.

Try a few variations

# A shorter chain — order.pay resolves to 5 steps, not 7
reqloom run order.pay

# No prerequisites at all: a public listing endpoint
reqloom run product.list

# Machine-readable output, for CI
reqloom run refund.approve --format json

# JUnit, for a CI test report
reqloom run refund.approve --format junit --output results.xml

# Override a variable for one run only
reqloom run order.create --var baseUrl=http://localhost:4000

Each one resolves its own chain. product.list has no dependencies, so it’s a single step — Reqloom adds nothing when nothing is needed.

What you saw

• One command per endpoint. No glue scripts, no ordering by hand.
• Chains derived, not written. From depends_on and {{X.y}} references.
• Multi-actor by default. Three identities, three cached logins, zero tokens in your clipboard.
• Deterministic order. The same schema resolves the same chain every run.

Next

• The mental model — the four ideas behind this
• Authoring guide — write one for your own API
• reqloom run — every flag and output format
• AI importer — bootstrap a schema from an existing spec