API Form: submit fields and handle the result

Submit named form controls, validate user input and react to the returned JSON without a page navigation.

Before you begin

• An App Connect page and an endpoint whose request fields and JSON response shape you know. Use a development endpoint for write examples.

Use the form as the request boundary

API Form submits a browser request to the configured API URL. It extends the Server Connect Form runtime. The endpoint must accept the chosen field encoding and return JSON for a successful request.

Configure the form and the endpoint

Select the form in App Structure. Put a named input and a submit button inside it; do not nest forms.

Control or value	Meaning and use
ID / Method	Use a unique ID such as saveForm. POST is appropriate for the example write; GET places fields in the URL and should be used for a read/search workflow.
Url / Define API Schema	Url is the endpoint. Define API Schema supplies metadata for input/output pickers; the endpoint remains responsible for its own validation.
Post Type	Form sends FormData, including selected files. JSON serializes field values, not file contents. Use Form for file uploads.
Auto Submit	Runs submission after initialization. Leave off when the user must finish or confirm data first. It uses the normal validation/submission path.
Query Parameters / API Headers	Set query and header pairs on the component. They are separate from named form fields in the body.
Submit	Runs client validation and the cancelable Submit event before sending. A submit button uses this path.
Reset	Restores form controls to their initial values. The default reset does not clear the last response data.

Example: submit a title and check the returned id

Create saveForm with a required text input named title and a submit button. Use a development endpoint accepting title and returning {“record”:{“id”:42,“title”:“Notebook”}}. Enter Notebook and submit. Read saveForm.data.record.id on Success. Bind the button’s disabled state to saveForm.state.executing to discourage duplicate submissions. Keep server validation and record authorization even when the page validates successfully.

Keep field names and encoding consistent

Form encoding follows named successful controls, including selected files; disabled controls are omitted. JSON mode turns nonempty number inputs into numbers, supports bracketed names for nested data, and gives checkboxes/radios with explicit values their selected value; without an explicit value the JSON parser uses a boolean. Do not assume changing Post Type leaves the payload shape unchanged. Inspect the request expected by the endpoint.

Handle invalid input at the matching field

Invalid can occur before any request or after HTTP 400. For server validation, the runtime can map response.form field names to matching [name] controls when the validation extension is loaded. Give users a way to correct each field. A successful response does not automatically clear their input. A later failure preserves previous response data, so do not treat an old id as proof the current submit succeeded.

Distinguish completion from success

Use Success for work that depends on a successful JSON response. Done also runs after errors and aborts, so it is suitable for cleanup rather than a saved-successfully message.

Control or value	Meaning and use
Start / state.executing	A request starts; disable repeated submission or show a loading indicator while executing is true.
Success / data	The HTTP path accepts status below 400 only when the response parses as JSON. Empty 204 responses and HTML login pages produce a JSON error.
Invalid / Unauthorized / Forbidden / Rate Limit	HTTP 400 / 401 / 403 / 429 have distinct event branches. Handle the applicable branch; these do not also trigger the generic Error event.
Error / lastError	Other HTTP failures, transport failures, timeouts or invalid successful JSON. Inspect status, message and response; do not expose private server details in a public error label.
Abort / Done	Abort ends the browser request. It does not undo work already accepted by the server. Done means the attempt ended.
Upload / Download	Progress events expose loaded, total and lengthComputable. Progress objects provide position, total and percent. Upload at 100% means bytes were sent; server processing can still fail.

Request options and implementation boundaries

The HTTP timeout attribute is in seconds. The runtime sends an X-CSRF-Token header when a csrf-token meta element is present; the server must still validate it. Upload progress reaching 100% does not mean the server finished processing. In the installed rules, the API Form Submit action presents Query Parameters, but the inherited runtime submit argument is the Direct flag. Set query parameters on the component and use a submit button; do not rely on passing an object to Submit, which can skip validation.

Continue with the matching workflow

Use the related guide to build and check the surrounding page workflow.

Check your result

You can configure the request, bind its real output and distinguish a successful result from loading, validation and error states.