Braids Documentation

Config-driven API composition — declare integrations in YAML, get a unified API.

What is Braids?#

Braids is a config-driven API composition tool. You define connectors and schemas in a single YAML file (braids.yaml) and get a unified HTTP API that merges data from multiple upstream sources into the shape you choose. It ships as a single Go binary with zero runtime dependencies — install it, write your config, and run braids serve.

How it works#

1. Define your config

Declare connectors, endpoints, and field mappings in braids.yaml:

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

schemas:
  customer:
    fields:
      id:    { type: string }
      name:  { type: string }
      email: { type: string }

endpoints:
  /users:
    schema: customer
    sources:
      - connector: stripe
        resource: customers
        mapping:
          id:    id
          name:  name
          email: email

2. Start the gateway

Run the server locally or deploy it anywhere:

$ braids serve

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

✓ Config loaded            braids.yaml
✓ Connector ready          stripe
✓ Schema validated         1 endpoint, 1 source

■ Gateway listening on     http://localhost:8080

3. Query your unified API

Every upstream source is merged into a single response:

$ curl http://localhost:8080/users

{
  "data": [
    {
      "id":    "cus_abc123",
      "name":  "Ada Lovelace",
      "email": "[email protected]"
    }
  ]
}

Explore the docs#

Quick Start#

Up and running in 30 seconds:

$ brew install braidsdev/tap/braids
$ braids init --demo
$ braids serve

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

✓ Config loaded            braids.yaml
✓ Connector ready          dummyjson
✓ Connector ready          jsonplaceholder

■ Gateway listening on     http://localhost:8080

$ curl http://localhost:8080/users

{
  "data": [
    {
      "id":    "cus_abc123",
      "name":  "Ada Lovelace",
      "email": "[email protected]",
      "plan":  "pro"
    },
    {
      "id":    "cus_def456",
      "name":  "Grace Hopper",
      "email": "[email protected]",
      "plan":  "enterprise"
    }
  ],
  "meta": {
    "sources": ["stripe", "internal"],
    "latency_ms": 42
  }
}