Kappapps SDK

Appearance

Class: ApiService ​

The SDK's HTTP client for calling the app's backend API: sending requests, fetching data, uploading files, and usage statistics. Requests go through a queue (concurrency and rate limiting) and are signed with the app's authentication token.

Remarks ​

Available everywhere via k.api. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.

In most cases, prefer `requestData` (which returns the data payload directly) over `request` (which returns the raw response).

Example ​

ts
// Read data, then write it
const score = await k.api.requestData('score', 'GET');
await k.api.request('score', 'POST', { value: score + 1 });

Implements ​

Properties ​

options ​

ts
options: ApiServiceOptions;

Service options (notably debug to periodically log stats).

Methods ​

file() ​

ts
file(
   endpoint, 
   blob, 
name?): Promise<any>;

Sends a file (blob) as multipart/form-data to the app's API.

Parameters ​

endpoint ​

string

Endpoint path relative to the app's API (a leading /, if any, is stripped). null targets the root of the app's API.

blob ​

Blob

The binary content to upload.

name? ​

string = null

Requested file name. If null, ask the endpoint to generate a name; the multipart file still uses kapp.name as its transport fallback.

Returns ​

Promise<any>

A promise resolved with the server's response, rejected on an HTTP error.

Default Value ​

null

Remarks ​

Uses the same queue and HTTP timeout as request. Closing the app cancels queued uploads and aborts transfers already in progress.

Example ​

ts
const blob = await (await fetch(dataUrl)).blob();
const resp = await k.api.file('upload', blob, 'capture.png');

request() ​

ts
request(
   endpoint?, 
   method?, 
data?): Promise<any>;

Sends an HTTP request to the app's API and returns the raw response (including the status / data envelope). The request is queued and authenticated automatically.

Parameters ​

endpoint? ​

string = null

Endpoint path relative to the app's API (a leading /, if any, is stripped). null targets the root of the app's API.

method? ​

ApiRequestMethod = 'GET'

HTTP method to use.

data? ​

ApiRequestData = {}

Request body (sent as JSON for methods other than GET, as query parameters for GET).

Returns ​

Promise<any>

A promise resolved with the raw response, rejected on an HTTP error (the error object contains reason and status if the response is not JSON).

Default Value ​

null

Default Value ​

'GET'

Default Value ​

{}

Remarks ​

Handles asynchronous responses: if the backend returns an async_http_response_id, the promise is only resolved once the corresponding deferred response arrives.

Example ​

ts
const resp = await k.api.request('score', 'POST', { value: 10 });

See ​

requestData to retrieve the data payload directly.

requestData() ​

ts
requestData(
   endpoint?, 
   method?, 
data?): Promise<any>;

Like `request`, but returns the payload (response.data) directly instead of the raw response.

Parameters ​

endpoint? ​

string = null

Endpoint path relative to the app's API.

method? ​

ApiRequestMethod = 'GET'

HTTP method to use.

data? ​

ApiRequestData = {}

Request body.

Returns ​

Promise<any>

The data value returned by the API, or null if the response contains none.

Default Value ​

null

Default Value ​

'GET'

Default Value ​

{}

Example ​

ts
const score = await k.api.requestData('score', 'GET');

See ​

requestDataOrNull which turns a 404 into null instead of rejecting.

requestDataOrNull() ​

ts
requestDataOrNull(
   endpoint?, 
   method?, 
data?): Promise<any>;

Variant of `requestData` that returns null when the API responds with 404 instead of rejecting the promise.

Parameters ​

endpoint? ​

string = null

Endpoint path relative to the app's API.

method? ​

ApiRequestMethod = 'GET'

HTTP method to use.

data? ​

ApiRequestData = {}

Request body.

Returns ​

Promise<any>

The data payload, or null if it is absent or if the API responds with 404. Other errors are propagated (the promise is rejected).

Default Value ​

null

Default Value ​

'GET'

Default Value ​

{}

Example ​

ts
// No error if the resource does not exist yet
const config = await k.api.requestDataOrNull('config', 'GET');
if (config === null) {
    // initialize a default config
}

stats() ​

ts
stats(): ApiStatsResponse;

Returns aggregated statistics about recent requests (size of the retained history), useful for diagnosing latency.

Returns ​

ApiStatsResponse

An ApiStatsResponse object: number of requests taken into account, average time spent waiting in the queue (queued_duration) and average request time (request_duration), expressed in milliseconds (string suffixed with ms).

Example ​

ts
console.log(k.api.stats());
// { requests: 12, queued_duration: '4ms', request_duration: '120ms' }