Build backend operations
An app needs a backend when a user asks for a result or makes a change: look up an order, calculate a quote, save an approval, or create a work order. Implement that request as a Python API and call it from the interface.
Use an API for request/response work. Use a transform for longer background calculations that publish reusable tables. An API can read those prepared results instead of repeating the calculation on every request.
Separate caller inputs from managed dependencies
Your coding agent declares both in Python:
from vortexify import Input, vxfy_api
@vxfy_api("/normalize", inputs={"value": Input(str, default="Hello")})
def api(value: str) -> dict:
text = value.strip()
return {"value": text, "length": len(text)}Input is a scalar the caller supplies: a string, integer, float, or boolean. Data, secrets, and database connections are different declarations that the backend resolves:
| Need | Declaration |
|---|---|
| Read a synced dataset | Table("shop.orders") |
| Read an uploaded dataset | Table("_upload.orders") |
| Read a prepared calculation | TransformOutput("order_totals") |
| Read database rows as a table | DatabaseTable("operations.work_orders") |
| Perform scoped operational SQL | Database("operations", tables=["work_orders"], mode="read_write") |
| Use a managed credential | Secret("erp_token") |
These references belong in the API's inputs mapping, under local argument names. The browser supplies caller inputs; it does not send database credentials or the contents of managed tables. Create required secrets through platform configuration or the CLI.
For Pandas, tabular inputs arrive as DataFrames. DuckDB registers them as relations under their local input names and injects conn. A tabular declaration does not automatically filter to the requested customer or record; implement that filtering and the necessary checks in your function. For operational writes, use parameterized SQL against the scoped database connection.
Prepare dependencies before invoking the API
Check that required sync or transform outputs have been published, database migrations are applied, and secrets have values. Declaring references does not create or run upstream resources.
The resource name, Python function name, and decorator path can differ. The CLI and React SDK call the registered resource name, such as normalize.
Your coding agent saves the intended code and prepares its preview runtime:
vortexify commit --type api --resource normalize
vortexify build api normalize --wait
vortexify test api normalize --wait
vortexify run api normalize --waitA build prepares the runtime and dependencies. Mock tests check behavior using test inputs. A manual run invokes the saved API against live resolved dependencies. Use an inputs file for request values; see CLI execution for syntax.
A preview invocation still performs writes implemented by the function. Waiting observes the existing request/job; a stopped wait does not undo it. Inspect its result before submitting the same write again.
Give the interface a useful response
Return JSON-compatible values with a stable shape. Convert database rows, DataFrames, dates, decimals, and missing numeric values explicitly. APIs return a response; they do not publish transform output tables.
Keep validation required for every request inside the function. Optional SDK response validation is a separate diagnostic step and is skipped for deployed API calls. Tests should cover meaningful behavior, such as invalid inputs or a missing record, using mocks for external side effects.
In the platform, open the API Playground. Configure prepares the runtime or runs tests, Run accepts scalar inputs as a JSON object, and History lists executions. Select a run to inspect Output, Processing, Logs, or the full JSON result. Code can show working source or a read-only saved version. Compare that run's response to what the interface expects before wiring up the screen.
Platform screenshot placeholder: An API execution with its saved version, scalar request inputs, response, and a link to execution logs.
Next: Build your interface. See API contracts, database configuration, and testing and validation for details.