Getting Started

Install Braids, create your first config, and query a unified API in under a minute.

Installation #

Homebrew (recommended)

$ brew install braidsdev/tap/braids

Shell script

$ curl -fsSL https://braids.dev/install.sh | sh

Go install

$ go install github.com/braidsdev/braids@latest

Docker

$ docker pull ghcr.io/braidsdev/braids:latest

Verify the installation:

$ braids version
braids v0.2.0 (abc1234)

Initialize a Project #

Run braids init in any directory to generate a starter braids.yaml pre-configured with a Stripe + Shopify example:

$ braids init
Created braids.yaml

If a braids.yaml already exists in the current directory, the command will exit without overwriting it.

The generated file looks like this:

version: "1"

connectors:
  stripe:
    type: stripe
    config:
      api_key: ${STRIPE_API_KEY}

  shopify:
    type: shopify
    config:
      store: ${SHOPIFY_STORE}
      access_token: ${SHOPIFY_ACCESS_TOKEN}

schemas:
  customer:
    merge_on: email
    conflict_resolution: prefer_latest
    fields:
      id:
        type: string
      email:
        type: string
      name:
        type: string
      created_at:
        type: datetime

endpoints:
  /customers:
    schema: customer
    sources:
      - connector: stripe
        resource: customers
        mapping:
          id: "'stripe_' + id"
          email: email
          name: name
          created_at: created

      - connector: shopify
        resource: customers
        mapping:
          id: "'shopify_' + id"
          email: email
          name: "first_name + ' ' + last_name"
          created_at: created_at

Demo Mode #

Want to try Braids without signing up for any API keys? The --demo flag generates a config that uses JSONPlaceholder and DummyJSON -- two free, public APIs that require no authentication.

$ braids init --demo
Created braids.yaml
Next steps:
  1. Run: braids validate
  2. Run: braids serve
  3. Try: curl http://localhost:8080/users

$ braids serve

■ Braids Gateway v0.2.0
────────────────────────────────────

✓ Config loaded            braids.yaml
✓ Connector ready          dummyjson
✓ Connector ready          jsonplaceholder
✓ Schema validated         1 endpoint, 2 sources
✓ Merge strategy           prefer_latest on "email"

■ Gateway listening on     http://localhost:8080

  Endpoints:
  GET  /users               jsonplaceholder + dummyjson

  Press Ctrl+C to stop

$ curl http://localhost:8080/users | jq '.'

Expected response:

[
  {
    "id": "jp_1",
    "email": "[email protected]",
    "name": "Leanne Graham",
    "source": "jsonplaceholder"
  },
  {
    "id": "dj_1",
    "email": "[email protected]",
    "name": "Emily Johnson",
    "source": "dummyjson"
  },
  ...
]

Validate #

Before serving, run braids validate to catch configuration errors early. The validator checks:

• version field is present and supported
• All connectors have a valid type and required config fields
• All schemas reference valid field types (string, number, boolean, datetime, object, array)
• All endpoints reference defined schemas and connectors
• Port range is valid (1–65535) if server.port is specified

Success output:

$ braids validate
braids.yaml is valid
  connectors:  2 (stripe, shopify)
  schemas:     1 (customers)
  endpoints:   1 (/customers)

Example error output:

$ braids validate
Error: validation failed

  - endpoints./customers.sources[1].connector: connector "stripe2" is not defined
  - schemas.customers.fields.age.type: unsupported type "int" (use "number")

Serve #

Start the gateway with braids serve. The startup banner displays the loaded config file, active connectors, registered endpoints, and the address the server is listening on.

$ braids serve
  ____            _     _
 | __ ) _ __ __ _(_) __| |___
 |  _ \| '__/ _` | |/ _` / __|
 | |_) | | | (_| | | (_| \__ \
 |____/|_|  \__,_|_|\__,_|___/

 Config:      braids.yaml
 Connectors:  stripe, shopify
 Endpoints:   /customers
 Listening:   http://localhost:8080

Make your first request:

$ curl http://localhost:8080/customers | jq '.'

Braids fetches from Stripe and Shopify in parallel, merges the results on the email field, and returns a unified response matching your schema.

Environment Variables #

Connector configs support ${VAR_NAME} substitution. At startup, Braids replaces every ${...} placeholder with the matching environment variable.

Set your variables with a .env file or export:

$ export STRIPE_API_KEY=sk_test_abc123
$ export SHOPIFY_STORE=my-store
$ export SHOPIFY_ACCESS_TOKEN=shpat_xyz789
$ braids serve

Or use a .env file in the same directory as your braids.yaml:

STRIPE_API_KEY=sk_test_abc123
SHOPIFY_STORE=my-store
SHOPIFY_ACCESS_TOKEN=shpat_xyz789

Hot Reload #

When server.hot_reload is set to true in your config, the gateway watches braids.yaml for changes and reloads automatically -- no restart required.

server:
  port: 8080
  hot_reload: true

After saving a change to your config, you will see:

[reload] braids.yaml changed — reloading config
[reload] done (12ms)

Braids applies a short debounce (100ms by default) to avoid reloading multiple times during rapid successive saves. In-flight requests complete against the previous configuration; new requests use the updated config.

Debug Mode #

Use the --debug flag to enable verbose logging. Every upstream request and response is logged, which is useful for troubleshooting connector issues or mapping problems.

$ braids serve --debug

Example debug output:

[debug] GET  https://api.stripe.com/v1/customers 200 OK (142ms)
[debug] GET  https://my-store.myshopify.com/admin/api/2024-01/customers.json 200 OK (238ms)
[debug] merge customers: 47 stripe + 31 shopify = 62 merged (16 matched on email)
[debug] response /customers 200 OK (284ms)