38 lines
2.2 KiB
Plaintext
38 lines
2.2 KiB
Plaintext
---
|
|
title: "Custom API"
|
|
description: "Renders an administrator-defined Custom JSX v2 widget with server-side API requests, options, and actions."
|
|
hide_title: true
|
|
---
|
|
|
|
import { WidgetHeader } from "@site/src/components/widgets/header";
|
|
import { AddingWidget } from "@site/src/components/widgets/adding";
|
|
import { customApiWidget } from ".";
|
|
|
|
<WidgetHeader widget={customApiWidget} categories={["Custom", "API"]} />
|
|
|
|
The Custom API widget displays a Custom JSX v2 definition created in [Management → Custom Widgets](/docs/management/custom-widgets). A definition owns one or more inline API sources, named requests, an options schema, and one safe JSX template. Temporary bound inputs exist only while the tile is mounted. Source credentials are encrypted separately and never reach the browser or an export.
|
|
|
|
### Add the widget
|
|
|
|
<AddingWidget />
|
|
|
|
Choose a definition from the searchable picker, configure its generated options, and select a refresh interval. The board item stores only the selected definition ID and validated option values; credentials remain server-side.
|
|
|
|
:::note
|
|
|
|
A definition must be enabled and available to the board before it appears in the widget picker.
|
|
|
|
:::
|
|
|
|
### Permissions and actions
|
|
|
|
Each request declares its minimum board permission independently of its HTTP method. Queries and actions may use GET, POST, PUT, PATCH, or DELETE; `kind` controls runtime behavior. DELETE always requires full board permission and confirmation. Anonymous viewers cannot execute actions.
|
|
|
|
Interactive controls are disabled while the board is in edit mode. Actions run only after an explicit user gesture and are never triggered by mounting, refresh polling, or automatic retries. Authoring previews simulate actions unless an administrator explicitly enables live actions for the short-lived preview session.
|
|
|
|
### Refresh behavior
|
|
|
|
The refresh interval reruns load-triggered queries. Manual queries run through `SubFetch`, and each query may declare its own cache duration. Successful actions can invalidate only their declared load or manual queries.
|
|
|
|
See [Custom Widgets management](/docs/management/custom-widgets) for the workbench, options, named-request manifest, Mantine JSX surface, network scopes, and security limits.
|