Call an external API — Reference

Configure an outgoing API Action and deliberately handle its response or failure.

Before you begin

• A Server Connect action and an endpoint you are authorized to call. The examples use illustrative addresses and do not contact a live service.

What API Action does

API Action runs on the server and makes an outgoing HTTP request. Its result contains status, headers and data; a page sees that result only if the enclosing action returns it. This reference covers the installed Node.js and PHP implementations. The same inspector labels do not guarantee identical runtime behavior.

Request settings

Setting	Meaning and example
ID	Names this step’s result in the action scope. For example, name it api_products and use api_products.data in later steps. A name does not create an API endpoint or authenticate the caller.
Output	Adds the named result to the action’s response data. Later server steps can use the result even when Output is off. The rule initializes new API steps with Output on, although its default declaration is false; check the saved step. Turn it off when the remote response contains fields the page should not receive.
Throw Errors	Requests an exception for an HTTP error response so an enclosing Try/Catch can handle it. Turn Pass Errors off when you intend to catch the response yourself. For example, catch a remote 422 and return your own validation message. Transport errors may also throw.
Pass Errors	Forwards a remote HTTP error to the caller. The runtime default is on. Turn it off to inspect api_products.status and handle the error within the action. When both error flags are on, Node.js forwards HTTP errors before its throw branch, while PHP checks Throw Errors first; avoid relying on that difference.
Timeout	Limits the outgoing request, with different units in the installed runtimes: Node.js uses milliseconds; PHP passes the value to cURL in seconds. For a five-second limit use 5000 in Node.js or 5 in PHP. An omitted Node.js timeout is 0, meaning no timeout from this option. Confirm the value when changing server models.
Url	The remote URL the server will request, for example https://api.example.test/products. It may use server data bindings. Keep the base URL free of a query string when using Query: the installed Node.js implementation appends a new question mark, whereas PHP appends question mark or ampersand as needed.
Method	The outgoing HTTP method. With no method saved, the runtime uses GET. Choices are GET, POST, PUT, PATCH and DELETE. For example, GET retrieves products; POST with the matching payload creates a record only if the remote API defines that operation.
Data Type	Chooses how the outgoing body is encoded; it does not define the response schema. Auto with POST selects form encoding. JSON selects application/json; Form uses application/x-www-form-urlencoded. The installed runtimes differ for Text: Node.js preserves a string, while the PHP implementation JSON-encodes non-form data. Verify the exact payload and Content-Type required by the remote API.
Text Data	The outgoing data value used when Text is selected. For Node.js raw text, set an explicit Content-Type header such as text/plain if required; the automatic type derived from Text is application/text. PHP does not share the same raw-string behavior in the installed implementation.
JSON Data	The outgoing JSON body. The editor validates a literal JSON value unless it is a dynamic expression. For example, {"name":"Notebook","price":12.5} supplies an object to a POST endpoint. Use data bindings for values that come from validated server inputs.
Authorization	Selects the outgoing remote-service authentication controls: None, Basic or OAuth2. It does not protect this Server Connect endpoint from its own callers; add server-side access checks separately when needed.
User Name	The user name for outgoing HTTP Basic authentication. Configure the remote-service account expected by that API and use HTTPS. The value is combined with Password; it is not a Wappler application-user login.
Password	The corresponding remote-service Basic authentication password. Bind a server-side configured secret rather than returning it to the page or embedding it in client code.
OAuth2	Selects an OAuth provider defined for the server action. The runtime obtains that provider’s access token and adds a Bearer Authorization header when a token is available. Complete the provider’s authorization flow first; selecting its name does not create a token.
Define API Schema	Describes the remote response for the editor’s data picker. For example, define data.products as an array with id, name and price fields. Schema metadata does not validate, transform or fabricate the HTTP response at runtime; compare it with a real response.
Input Data	Name/value pairs for an outgoing form or automatic body. For example, a field name query and value notebook produces a form-encoded query value with POST/Auto. This is distinct from the action’s incoming $_POST inputs.
Query	Name/value pairs encoded into the outgoing URL. For example, search = a&b becomes search=a%26b. Supply an unencoded value and let the module encode it. Use a clean base URL, especially on Node.js.
Headers	Outgoing request headers. For example, Accept = application/json requests JSON from the remote API, and Content-Type controls the request payload format. A response may still have a different type; inspect the returned headers and data.

Read the result

For a step named api_products, read api_products.status for the remote HTTP status and api_products.data for the body. Node.js parses the body when Content-Type contains json; PHP attempts JSON parsing regardless of that header. A non-JSON body can therefore remain text. A 204 or empty body need not be a failure.

Json

{"api_products":{"status":200,"headers":{"content-type":"application/json"},"data":{"products":[{"id":1,"name":"Notebook","price":12.5}]}}}

Example: load and inspect products

Add API Action, name it api_products, set Url to your products endpoint and choose GET. Add Query name search with value notebook. Set Pass Errors off so the action can inspect the returned status. Leave Throw Errors off for a status-based Condition, or turn it on and place the step inside Try/Catch. A 200 response with data.products containing one record should make api_products.data.products available to the next server step. Return only the fields the page needs.

Choose the failure path

Use one deliberate HTTP-error strategy: forward the remote failure, branch on its returned status, or catch an exception. Do not depend on both error switches being on because their precedence differs between Node.js and PHP. Test a successful response, an HTTP error, an empty result and an unreachable endpoint separately. Network failures are different from a remote API returning a normal HTTP response with an error status.

Runtime details to verify

The installed runtime supports a verifySSL option, defaulting to false, but this inspector rule does not expose a control for it. Certificate verification therefore must not be assumed from using an https URL alone. Review the deployed runtime configuration for authenticated remote requests. Also verify timeout units and Text-body encoding before switching server models.

From request to page

After verifying the server response, return a deliberately shaped output and load this action with an App Connect Server Connect component. The component’s page-side data picker is separate from the outgoing API schema used by this server step.

Check your result

You can identify the outgoing URL, method and body, read status/headers/data, and choose explicit error behavior for your server model.