# API Client

HTTP requests with parameters, authentication, and typed responses.

URL: https://webrad.atentor.com/docs/api-client
Updated: 2026-11-07

WebApiClient · Nonvisual · Nonvisual · 4 events

## Quick start

Add **ApiClient1** in the Designer. Use the example in a page method.

```ts
// Configure a Load operation with the id parameter.
const request = ApiClient1.RequestByName('Load');
request.parameter.id = 42;
try {
  const result = await request.execute();
  console.log(result);
} catch (error) {
  Message(error instanceof Error ? error.message : String(error));
}
// The generated typed accessor also supports ApiClient1.Load.execute().
```

Use lowercase parameter and execute; Connection, Query, Headers, Body, and Response retain their capitals. Failures reject the Promise and trigger the corresponding events.

- Open the editor and create operations with a name, method, endpoint, parameters, and response schema.
- Use the generated accessor, such as ApiClient1.Load.parameter.id and ApiClient1.Load.execute(), or RequestByName('Load').
- Placeholders such as <id> in paths or bodies use parameter values. Query, Headers, and Body configure the remaining inputs.
- **Import from RestGo** imports published APIs. **Refresh** synchronizes imported clients while preserving their IDs and names.
- Choose **Custom API**, **RestGo JWT Authentication**, **RestGO API Token**, or **RestGO Public** to match the API. Each client uses one authentication mode.
- To test JWT in the editor, use Development login in RestGo integration → Connection or enter Test JWT.
- get/post/put/patch/delete support direct calls. status, error, Response, and events track the result.

## Authorization for a Custom API

1. Open the API Client editor, select a request, and open **Authorization**.
2. In **Apply to**, choose **Client defaults** to configure a shared default or **This request** to override it. A request can choose **Inherit from client**; the client can choose **Use manual headers**.
3. Select **No auth**, **Basic Auth**, **Bearer Token**, or **API Key**. For Basic enter username and password; for Bearer enter the token without the Bearer prefix or whitespace. For API Key specify its name, value, and Header or Query parameter destination. Save the configuration.
4. Execute the configured operation from an event, for example ApiClient1.Load.execute(), or use ApiClient1.execute('Load'). A per-call authorization option overrides the request setting, which overrides the client default. With manual headers and no explicit authorization, existing Authorization headers are retained. Explicit authorization replaces the Authorization header; **No auth** removes it. An API key replaces the configured header or query parameter of the same name.

Credentials saved in the editor are stored in the project and included in generated browser applications. Use credentials intended for client-side use; masking a field in the editor does not make it secret. Code can assign ApiClient1.Connection.Authorization for the client, ApiClient1.Request.Authorization for the active request, or pass an authorization option per call. RestGo connection modes manage authorization automatically and do not accept these Custom API authorization settings. Browser CORS and server policies still apply.

## More examples

Connection, query, headers, body, timeout, and response

```ts
// Requires an active operation configured in the Designer.
ApiClient1.Connection.Mode = 'custom';
ApiClient1.Connection.BaseURL = 'https://api.example.com';
ApiClient1.Connection.Timeout = 15_000;
ApiClient1.Method = 'POST';
ApiClient1.Endpoint = '/customers';
ApiClient1.Query['source'] = 'web';
ApiClient1.Headers['X-Source'] = 'WebRAD';
ApiClient1.Body.Kind = 'json';
ApiClient1.Body.Value = '{"name": "Ana"}';
ApiClient1.Options.Timeout = 10_000;
ApiClient1.Options.ResponseType = 'json';
ApiClient1.Options.Credentials = 'omit';
const result = await ApiClient1.execute();
console.log(result, ApiClient1.Response.Status, ApiClient1.Response.Value);
```

Cancellation and response types in direct calls

```ts
const controller = new AbortController();
try {
  const result = await ApiClient1.get('/customers', {
    query: { page: 1, active: true },
    headers: { Accept: 'application/json' },
    responseType: 'json',
    timeoutMs: 10_000,
    signal: controller.signal,
  });
  console.log(result);
} catch (error) {
  Message(error instanceof Error ? error.message : String(error));
}
// To cancel from another action: controller.abort().
// responseType accepts auto | json | text | blob | arrayBuffer.
```

Authorization for a configured request

```ts
// Configure the Load operation on a Custom API client first.
ApiClient1.RequestByName('Load').Authorization = { type: 'bearer', token: 'CLIENT-SIDE-TOKEN' };
const result = await ApiClient1.execute('Load');
console.log(result);
// Restore inheritance from client defaults for this request:
ApiClient1.RequestByName('Load').Authorization = null;
```

Per-call authorization override

```ts
// The Load operation must exist on a Custom API client.
const result = await ApiClient1.execute('Load', {
  authorization: { type: 'api-key', name: 'X-API-Key', value: 'CLIENT-SIDE-KEY', in: 'header' },
});
console.log(result);
// Use { type: 'none' } to explicitly omit Authorization for a call.
```

Client default and API key in the query

```ts
// Use only credentials intended for browser applications.
ApiClient1.Connection.Authorization = {
  type: 'basic', username: 'CLIENT-USER', password: 'CLIENT-PASSWORD',
};
// A request can instead send a key in a query parameter:
ApiClient1.RequestByName('Load').Authorization = {
  type: 'api-key', name: 'api_key', value: 'CLIENT-SIDE-KEY', in: 'query',
};
await ApiClient1.execute('Load');
// Query parameters may be visible in server logs and browser history.
```

## Inspector properties

Component options and defaults. Fields without runtime access are configured in the Inspector.

| Property / source | Type and options | Default | Runtime access |
| --- | --- | --- | --- |
| `name` — Name · Identity | `string` | `—` | name |
| `baseUrl` — Base URL · Connection — Custom API URL. RestGo-bound clients use the fixed URL from RestGo integration > Connection. | `string` | `""` | baseUrl — Conditional availability in the Inspector |
| `apiClientConfig` — Requests · API Client — Configure requests in the Designer; access RequestName.parameter and RequestName.execute() in code with typed request objects. | `api-client-config` — Editor: api-client-tester | `{"schemaVersion":1,"defaultHeaders":[],"timeoutMs":30000,"operations":[{"id":"operation-1","name":"Request","method":"GET","path":"","headers":[],"query":[],"body":{"kind":"none","content":""},"credentials":"omit","timeoutMs":null,"responseSchema":null}]}` | apiClientConfig |

## API in code

| Member | Signature | Access |
| --- | --- | --- |
| `baseUrl` | `get baseUrl(): string;` | Read and write |
| `apiClientConfig` — Immutable normalized contract configured for this client instance. | `get apiClientConfig(): WebApiClientConfiguration;` | Read and write |
| `Configuration` | `get Configuration(): WebApiClientConfiguration;` | Read and write |
| `Connection` | `get Connection(): WebApiConnectionSettings<TDefaultHeaders>;` | Read-only |
| `Operation` | `get Operation(): (keyof TOutputs & string) \| undefined;` | Read and write |
| `Requests` | `get Requests(): WebApiRequests<TOutputs, TInputs>;` | Read-only |
| `Request` | `get Request(): WebApiRequest<WebApiCombinedInputs<TInputs, 'Parameter'>, TOutputs[keyof TOutputs], WebApiCombinedInputs<TInputs, 'Query'>, WebApiCombinedInputs<TInputs, 'Headers'>>;` | Read-only |
| `parameter` | `get parameter(): WebApiParameterValues<WebApiCombinedInputs<TInputs, 'Parameter'>>;` | Read-only |
| `Query` | `get Query(): WebApiQueryValues<WebApiCombinedInputs<TInputs, 'Query'>>;` | Read-only |
| `Headers` | `get Headers(): WebApiHeaderValues<WebApiCombinedInputs<TInputs, 'Headers'>>;` | Read-only |
| `Body` | `get Body(): WebApiBodySettings;` | Read-only |
| `Authorization` | `get Authorization(): WebApiAuthorization \| null;` | Read and write |
| `Options` | `get Options(): WebApiRequestSettings;` | Read-only |
| `Response` | `get Response(): WebApiResponse<TOutputs[keyof TOutputs]>;` | Read-only |
| `Method` | `get Method(): string;` | Read and write |
| `Endpoint` | `get Endpoint(): string;` | Read and write |
| `ApiVersion` | `get ApiVersion(): number \| null;` | Read and write |
| `operations` — Saved operation metadata, safe for a Table or another consumer to inspect. | `get operations(): readonly WebApiOperation[];` | Read and write |
| `data` — Latest successful data, keyed by the configured operation name. | `get data(): Readonly<Partial<TOutputs>>;` | Read-only |
| `status` — State of the most recently executed operation. | `get status(): WebApiOperationStatus;` | Read-only |
| `error` | `get error(): unknown;` | Read-only |

### `withRequests`

method

```ts
withRequests(): WebApiClientInstance<TOutputs, TInputs, TDefaultHeaders>;
```

Typed view of the same instance, used by generated page and reusable code.

Example

```ts
const client = ApiClient1.withRequests();
console.log(client.status);
```

### `RequestByName`

method

```ts
RequestByName<K extends keyof TOutputs & string>(name: K): WebApiRequests<TOutputs, TInputs>[K];
RequestByName(name: string): WebApiRequest;
```

Example

```ts
ApiClient1.RequestByName('Load');
```

### `ParamByName`

method

```ts
ParamByName(name: string): WebApiNamedParameter;
```

Example

```ts
ApiClient1.ParamByName('id');
```

### `ClearParameters`

method

```ts
ClearParameters(): void;
```

Example

```ts
ApiClient1.ClearParameters();
```

### `getOperationState`

method

```ts
getOperationState<T = unknown>(operationName: string): WebApiOperationState<T>;
```

Example

```ts
ApiClient1.getOperationState('Load');
```

### `subscribe`

method

```ts
subscribe(listener: () => void): () => void;
```

Notifies runtime consumers whenever a named operation changes state.

Example

```ts
const unsubscribe = ApiClient1.subscribe(() => { console.log(ApiClient1.status); });
unsubscribe();
```

### `request`

method

```ts
request<T>(path: string, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.request('/customers', { method: 'GET' });
```

### `get`

method

```ts
get<T>(path: string, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.get('/customers');
```

### `post`

method

```ts
post<T>(path: string, body?: unknown, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.post('/customers', { name: 'Ana' });
```

### `put`

method

```ts
put<T>(path: string, body?: unknown, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.put('/customers/42', { name: 'Ana' });
```

### `patch`

method

```ts
patch<T>(path: string, body?: unknown, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.patch('/customers/42', { name: 'Ana' });
```

### `delete`

method

```ts
delete<T>(path: string, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.delete('/customers/42');
```

### `head`

method

```ts
head(path: string, options?: WebApiRequestOptions): Promise<void>;
```

Example

```ts
await ApiClient1.head('/customers');
```

### `options`

method

```ts
options<T>(path: string, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
await ApiClient1.options('/customers');
```

### `execute`

method

```ts
execute<K extends keyof TOutputs & string>(operationName: K, options?: WebApiRequestOptions): Promise<TOutputs[K]>;
execute(options?: WebApiRequestOptions): Promise<TOutputs[keyof TOutputs]>;
execute<T = unknown>(operationName: string, options?: WebApiRequestOptions): Promise<T>;
```

Example

```ts
const result = await ApiClient1.execute('Load', { parameters: { id: 42 } });
console.log(result);
```

### `getOutputById`

method

```ts
getOutputById<T = unknown>(operationName: string, schemaNodeIdOrPath: string): T | undefined;
```

Resolves any saved schema node from the latest result of one operation.

Example

```ts
ApiClient1.getOutputById('Load', '/data');
```

### `getList`

method

```ts
getList<T = unknown>(operationName: string, schemaNodeIdOrPath: string): readonly T[];
```

Returns a saved list output, or an empty readonly list when it is unavailable.

Example

```ts
ApiClient1.getList('Load', '/data');
```

Inherited members (5)

| Member | Signature | Access |
| --- | --- | --- |
| `id` | `readonly id: string;` | Read-only |
| `name` | `readonly name: string;` | Read-only |

### `bindEvent`

method

```ts
bindEvent(eventName: string, handler: WebComponentEventHandler<this> | null): () => void;
```

### `emit`

method

```ts
emit(eventName: string, detail?: unknown): boolean;
```

### `dispose`

method

```ts
dispose(): void;
```

## Connection, request, and response objects

The options below belong to the instance’s public objects. The active operation must exist in the project. For a named operation, use the same contract in ApiClient1.Load.

### ApiClient1.Connection

| Member | Signature | Access |
| --- | --- | --- |
| `Headers` | `readonly Headers: WebApiHeaderValues<THeaders>;` | Read-only |
| `Mode` | `get Mode(): WebApiConnection;` | Read and write |
| `BaseURL` | `get BaseURL(): string;` | Read and write |
| `Authorization` | `get Authorization(): WebApiAuthorization \| null;` | Read and write |
| `Timeout` | `get Timeout(): number;` | Read and write |
| `DefaultHeaders` | `get DefaultHeaders(): readonly WebApiParameter[];` | Read and write |

### ApiClient1.Request

| Member | Signature | Access |
| --- | --- | --- |
| `ID` | `readonly ID: string;` | Read-only |
| `parameter` | `readonly parameter: WebApiParameterValues<TParameters>;` | Read-only |
| `Query` | `readonly Query: WebApiQueryValues<TQuery>;` | Read-only |
| `Headers` | `readonly Headers: WebApiHeaderValues<THeaders>;` | Read-only |
| `Body` | `readonly Body: WebApiBodySettings;` | Read-only |
| `Options` | `readonly Options: WebApiRequestSettings;` | Read-only |
| `Response` | `readonly Response: WebApiResponse<TResult>;` | Read-only |
| `Name` | `get Name(): string;` | Read and write |
| `Method` | `get Method(): string;` | Read and write |
| `Authorization` — Null inherits the client default; explicit none suppresses Authorization. | `get Authorization(): WebApiAuthorization \| null;` | Read and write |
| `Endpoint` | `get Endpoint(): string;` | Read and write |
| `ApiVersion` | `get ApiVersion(): number \| null;` | Read and write |
| `Definition` | `get Definition(): WebApiOperation;` | Read and write |

### `ParamByName`

method

```ts
ParamByName(name: string): WebApiNamedParameter;
```

Example

```ts
ApiClient1.Request.ParamByName('id');
```

### `ClearParameters`

method

```ts
ClearParameters(): void;
```

Example

```ts
ApiClient1.Request.ClearParameters();
```

### `execute`

method

```ts
execute(options?: WebApiRequestOptions): Promise<TResult>;
```

Executes this request without changing the client's selected Operation first.

Example

```ts
const result = await ApiClient1.Request.execute({ parameters: { id: 42 } });
console.log(result);
```

### ApiClient1.Body

| Member | Signature | Access |
| --- | --- | --- |
| `Kind` | `get Kind(): WebApiBodyKind;` | Read and write |
| `Value` | `get Value(): string;` | Read and write |
| `Parameters` | `get Parameters(): readonly WebApiTemplateParameter[];` | Read and write |

### ApiClient1.Options

| Member | Signature | Access |
| --- | --- | --- |
| `Credentials` | `get Credentials(): WebApiCredentials;` | Read and write |
| `Timeout` | `get Timeout(): number \| null;` | Read and write |
| `ResponseType` | `get ResponseType(): WebApiResponseType;` | Read and write |

### ApiClient1.Response

| Member | Signature | Access |
| --- | --- | --- |
| `Value` | `get Value(): T \| undefined;` | Read-only |
| `Status` | `get Status(): WebApiOperationState['status'];` | Read-only |
| `Error` | `get Error(): unknown;` | Read-only |
| `UpdatedAt` | `get UpdatedAt(): number \| undefined;` | Read-only |
| `Schema` | `get Schema(): WebApiResponseSchema \| null;` | Read and write |

### ApiClient1.ParamByName('id')

| Member | Signature | Access |
| --- | --- | --- |
| `Name` | `readonly Name: string;` | Read-only |
| `Value` | `get Value(): WebApiParameterValue \| undefined;` | Read and write |
| `Type` | `get Type(): WebApiTemplateParameterType;` | Read and write |

### `Clear`

method

```ts
Clear(): void;
```

Example

```ts
ApiClient1.ParamByName('id').Clear();
```

## Events

Link methods in **Interaction**. [How to use events](https://webrad.atentor.com/docs/interactions).

### OnRequest

[WebApiOperationEventDetail](https://webrad.atentor.com/docs/types#webapioperationeventdetail) in `event.detail`

Signature and example

```ts
import type { WebApiClient, WebApiOperationEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ApiClient1Request(
    sender: WebApiClient,
    event: CustomEvent<WebApiOperationEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
  }
}
```

### OnSuccess

[WebApiOperationEventDetail](https://webrad.atentor.com/docs/types#webapioperationeventdetail) in `event.detail`

Signature and example

```ts
import type { WebApiClient, WebApiOperationEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ApiClient1Success(
    sender: WebApiClient,
    event: CustomEvent<WebApiOperationEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
  }
}
```

### OnError

[WebApiOperationEventDetail](https://webrad.atentor.com/docs/types#webapioperationeventdetail) in `event.detail`

Signature and example

```ts
import type { WebApiClient, WebApiOperationEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ApiClient1Error(
    sender: WebApiClient,
    event: CustomEvent<WebApiOperationEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
  }
}
```

### OnComplete

[WebApiOperationEventDetail](https://webrad.atentor.com/docs/types#webapioperationeventdetail) in `event.detail`

Signature and example

```ts
import type { WebApiClient, WebApiOperationEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async ApiClient1Complete(
    sender: WebApiClient,
    event: CustomEvent<WebApiOperationEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
  }
}
```