Routes

A route gives a flow an address under your API, with an HTTP method and a path that can contain parameters. POST /orders/{id}/pay is a route. It reads like the rest of a REST API and works from anything that can make an HTTP request, including your app.

Routes page — Logic → Routes: custom endpoints under /rest/v1, handled by a flow.

Routes are defined in Studio (Logic → Routes): a method, a path, an access rule, and the flow that handles it. From your app you call them through pawabase.routes.

Call a route

const status = await pawabase.routes.get("orders/42/status");
const paid = await pawabase.routes.post("orders/42/pay", { method: "card" });
const moved = await pawabase.routes.put("orders/42/address", { city: "Lagos" });
const edited = await pawabase.routes.patch("orders/42", { note: "Leave at the door" });
await pawabase.routes.delete("orders/42/items/7");

status = pb.routes.get("orders/42/status")
paid = pb.routes.post("orders/42/pay", method="card")
moved = pb.routes.put("orders/42/address", city="Lagos")
edited = pb.routes.patch("orders/42", note="Leave at the door")
pb.routes.delete("orders/42/items/7")

Paths are relative to your API’s /rest/v1/. A leading slash is ignored. Use the path exactly as the route was defined, with the real values in place of the {parameters}.

Query strings and bodies

const results = await pawabase.routes.get("search", {
  query: { q: "lagos", tag: ["a", "b"], page: 2 },   // arrays repeat the key: tag=a&tag=b
});

const created = await pawabase.routes.post("invoices", { customer: "c_9", lines: [{ sku: "A1", qty: 2 }] });

results = pb.routes.get("search", q="lagos", page=2)

created = pb.routes.post("invoices", customer="c_9", lines=[{"sku": "A1", "qty": 2}])

In Python, keyword arguments become the JSON body for post, put and patch, and the query string for get and delete. To send both a body and a query string, pass params={…} for the query:

pb.routes.post("invoices", params={"dry_run": "true"}, customer="c_9")

Any method with `call`

call(method, path, options) is the general form. The shortcuts are built on it.

const result = await pawabase.routes.call("POST", "orders/42/refund", {
  body: { reason: "damaged" },
  query: { notify: "true" },
  headers: { "x-source": "support" },
  timeoutMs: 20_000,
});

result = pb.routes.call("POST", "orders/42/refund", json={"reason": "damaged"}, params={"notify": "true"})

Type results (TypeScript)

type Status = { state: "pending" | "paid" | "shipped"; updatedAt: string };

const status = await pawabase.routes.get<Status>("orders/42/status");

Options

Option	Meaning
`query`	Query-string values. Arrays repeat the key
`body`	The JSON body (use the shortcut’s second argument instead for `post`, `put`, `patch`)
`headers`	Extra headers
`signal`	An `AbortSignal` to cancel
`timeoutMs`	Per-attempt timeout
`idempotent`	Allow retrying a `POST` after a network failure when running twice is harmless

GET is retried safely by the client after rate limits and temporary server errors. Other methods follow the idempotent flag.

Access and errors

A route has its own access rule, evaluated against the caller before anything runs. Errors are the standard ones:

try {
  await pawabase.routes.post("orders/42/pay", { method: "card" });
} catch (e) {
  if (e instanceof AuthenticationError) redirectToSignIn();
  else if (e instanceof PermissionError) show("This order isn't yours.");
  else if (e instanceof NotFoundError) show("No such order.");
  else if (e instanceof ValidationError) showFieldErrors(e.byField());
  else if (e instanceof ConflictError) show("Already paid.");
  else throw e;
}

try:
    pb.routes.post("orders/42/pay", method="card")
except AuthenticationError: ...
except ForbiddenError: ...
except NotFoundError: ...
except ConflictError: ...

Designing route paths

Use nouns and ids in the path, verbs in the method: POST /orders/42/refund, not POST /doRefund.
Keep ids in the path, optional filters in the query, and the details in the body.
Return 404 for an id that does not exist or that the caller may not see, so you do not leak which exist.
Return 409 for “already done”, and make repeating a call harmless.

Routes versus the database API

You already have from("orders") for plain create/read/update/delete on a table. Use a route when:

The action is not a simple row change (pay, refund, publish, invite).
You need to change several tables together, or validate across them.
You want a stable external API that does not expose your table shape.

Flows

The automation behind a route.

Patterns

Designs that combine them.

Server logic

Block reference

Call a route

Query strings and bodies

Any method with `call`

Type results (TypeScript)

Options

Access and errors

Designing route paths

Routes versus the database API

Flows

Patterns

​Call a route

​Query strings and bodies

​Any method with call

​Type results (TypeScript)

​Options

​Access and errors

​Designing route paths

​Routes versus the database API

Flows

Patterns

Call a route

Query strings and bodies

Any method with `call`

Type results (TypeScript)

Options

Access and errors

Designing route paths

Routes versus the database API