Skip to content

API Bridge ​

Every method is a suspend function and throws SkapiException with a code and a message. Values that fail a check throw INVALID_PARAMETER before anything is sent. Any method can throw NETWORK_ERROR when no answer comes back. A method that waits stops when its coroutine is cancelled. See Forwarding Requests.

A request is addressed by its request_id, or by its short id ("<stamp>:<entropy>") together with the url and method it was sent with. A signed-out caller can only reach its own requests from the same IP address and User-Agent; any other caller gets NOT_EXISTS (Request not found.).

forwardRequest ​

kotlin
suspend fun forwardRequest(options: JsonObject, form: Map<String, Any?>? = null, onStream: ((String, Int) -> Unit)? = null): JsonElement
java
CompletableFuture<Object> forwardRequest(Map<String, ?> options, Map<String, ?> form, BiConsumer<String, Integer> onStream)
// also forwardRequest(options) and forwardRequest(options, form)
// form values: plain Java values, byte[] or FileUpload

Calls another API from Skapi's server.

argument
optionsRequired. Keys below.
formValues: JsonElement, String, numbers, booleans, null, ByteArray or FileUpload (a list gives several). Merged into data, or into params for GET, DELETE and HEAD; an option's own key wins. With multipart, the multipart body.
onStream(text, seq), called with each relayed piece of a streamed request, in order, on a background thread. Exceptions it throws are logged and ignored.
option keytype
urlstringRequired. A full URL.
methodstring"GET", "POST" (default), "PUT", "PATCH", "DELETE", "HEAD", any case.
headersobjectNo name starting with x-skapi-.
dataobjectThe body: JSON when Content-Type is application/json, form-encoded otherwise.
paramsobjectThe query string.
secretNamestringA client secret of the project. Its value replaces "$CLIENT_SECRET" in url and in every string of headers, data and params. Left out when "$CLIENT_SECRET" appears nowhere.
skapiHeadersboolean or {"user"?: <boolean>, "service"?: <boolean>}Sends x-skapi-user (the signed-in user's ID) and x-skapi-service.
queuestringQueue the request on the server. No colons.
pollnumber or booleanMilliseconds between checks (true = 1000). Waits for the answer; makes a queue name when none is given.
streambooleanRelay the answer as it arrives. Queued and polled like poll.
expiresnumberSeconds the request stays in the history after it settles.
multipartbooleanSend form as multipart/form-data. Files are FileUpload values or ByteArrays.
responseType"json" or "text"Reshapes the answer. An envelope is returned unchanged.

"$ACCESS_TOKEN" anywhere in url, headers, data or params becomes the signed-in user's access token (empty when signed out). In Kotlin strings, write "\$CLIENT_SECRET" and "\$ACCESS_TOKEN".

Returns:

  • no queue, poll or stream: the destination's answer, parsed JSON or text, even when it looks like {"status": "pending", "id": ...}. Its status code is not returned.
  • queue without poll: {"id", "status": "pending", "queue_name", "in_queue", "request_id"}.
  • poll or stream: what forwardRequestPoll returns once the request settles.

Errors ​

codemessage
INVALID_PARAMETER"apiKeyHeader" and "apiKeyScheme" are no longer supported. Store the key as a client secret, name it with "secretName", and put "$CLIENT_SECRET" where the key goes.
INVALID_PARAMETER"url" should be type: <string>. / "<url>" is an invalid url.
INVALID_PARAMETER"method" should be one of "GET", "POST", "PUT", "PATCH", "DELETE" or "HEAD".
INVALID_PARAMETER"headers" should be type: <object>. / "data" should be type: <object>. / "params" should be type: <object>.
INVALID_PARAMETER"headers" cannot set "<name>": the "x-skapi-" prefix is reserved. Use "skapiHeaders" to tell the destination who the caller is.
INVALID_PARAMETER"skapiHeaders" should be type: <boolean> or { user?: boolean; service?: boolean }.
INVALID_PARAMETER<value> is invalid in "secretName". allowed type or value is: Type<string>. (also "queue"; Type<number> for "expires")
INVALID_PARAMETER"stream" should be type: <boolean>. / "multipart" should be type: <boolean>.
INVALID_PARAMETER"poll" should be a non-negative number.
INVALID_PARAMETER"responseType" should be either "json" or "text". / "responseType": "response" is not available here. ...
INVALID_PARAMETER"data" cannot be sent with "multipart": true. The form itself is the body.
INVALID_PARAMETER"multipart": true needs a form body in the first argument.
INVALID_PARAMETER"<name>" needs a filename. / "<name>" cannot be read: <reason>. (a FileUpload in a multipart form)
INVALID_PARAMETERMultipart body is too large: <n> bytes once base64 encoded, and the limit is 2031616. Upload the file first and send its url instead.
INVALID_REQUESTData should not exceed 2MB (form)
INVALID_REQUESTInvalid clientSecretName. / No access to client secret. (a locked secret and no signed-in user, or a lower access group)
INVALID_REQUESTa URL the secret's destinations do not allow
INVALID_REQUESTInvalid queue name. Queue names cannot contain colons.
ERRORthe destination could not be reached (inline request)

An error answer from the destination is not thrown: inline it is returned as the answer, queued it is the failed result below.

forwardRequestPoll ​

kotlin
suspend fun forwardRequestPoll(requestId: String, pollMillis: Long = 1000, url: String? = null, method: String? = null,
                               onStream: ((String, Int) -> Unit)? = null, service: String? = null, owner: String? = null): JsonElement
java
CompletableFuture<Object> forwardRequestPoll(String requestId, long pollMillis, String url, String method,
                                             BiConsumer<String, Integer> onStream, String service, String owner)
// leave out arguments from the right; forwardRequestPoll(requestId) checks every 1000 ms

Waits for a queued request and returns its result. The first check goes out after pollMillis milliseconds (0 means 1000). It suspends until the request settles; there is no time limit, so cancel the coroutine to stop waiting. With onStream, new text of a streamed request is handed over as it arrives.

argument
requestIdThe request_id, or the short id with url and method.
pollMillisMilliseconds between checks.
url, methodNeeded with a short id.
onStream(text, seq) for a streamed request.
service, ownerAnother project's request; left out, this project's.

Returns:

the requestreturns
resolvedthe destination's answer (or the finalized value of a streamed request)
failed{"status_code": <number>, "body": <string>, "truncated": ...}, or another error object such as {"message", ...}
cancelledthe envelope, "status": "cancelled"
streamed, not finalizedthe envelope: {"id", "status", "queue_name", "in_queue", "executed"?, "responded"?}, plus "stream", "chunks", "last_seq", "more" and, when failed, "error" with onStream

Errors ​

codemessage
INVALID_PARAMETER"poll" should be a non-negative number.
INVALID_PARAMETER"requestId" should be type: <string>. (an empty requestId)
INVALID_PARAMETER"url" and "method" are required to address a request by its short id. / "<url>" is an invalid url.
NOT_EXISTSRequest not found.

forwardRequestStream ​

kotlin
suspend fun forwardRequestStream(requestId: String, options: JsonObject? = null, onStream: ((String, Int) -> Unit)? = null): JsonElement
java
CompletableFuture<Object> forwardRequestStream(String requestId, Map<String, ?> options, BiConsumer<String, Integer> onStream)
// also forwardRequestStream(requestId) and forwardRequestStream(requestId, options)

Reads a streamed request, from the start or after since, and returns once it settles. The first read is immediate. Running: hands new text to onStream until it settles, then returns the envelope. Settled, not finalized: hands over all the stored text, then returns the envelope. Finalized: returns the kept value. After three degraded reads in a row on a settled request it returns what it has.

option keytype
url, methodstringNeeded with a short id.
sincenumberStart after this seq.
pollnumberMilliseconds between reads while it runs. Default 1000.

Errors ​

codemessage
INVALID_PARAMETER"poll" should be a non-negative number. / "since" should be a number.
INVALID_PARAMETER"requestId" should be type: <string>. / "url" and "method" are required to address a request by its short id. / "<url>" is an invalid url.
NOT_EXISTSRequest not found.

forwardRequestFinalize ​

kotlin
suspend fun forwardRequestFinalize(requestId: String, data: JsonElement? = null, options: JsonObject? = null): JsonElement
java
CompletableFuture<Object> forwardRequestFinalize(String requestId, Object data, Map<String, ?> options)
// also forwardRequestFinalize(requestId) and forwardRequestFinalize(requestId, data)

Stores data as a settled streamed request's answer and releases its pieces. Later polls return data; forwardRequestHistory lists it as response_body. Calling it again replaces the value. Without data, null is stored. options: url and method, needed with a short id.

Returns {"finalized": <boolean>, "message": <string>}. These come back with "finalized": false instead of throwing:

message
Finalized.done
Request not found.no such request for this caller
The request has not finished yet.it is still pending or running
The request was not sent with stream, so its response is already stored.not a streamed request
The request changed while it was being finalized. Try again.

Errors ​

codemessage
INVALID_PARAMETER"requestId" should be type: <string>. / "url" and "method" are required to address a request by its short id. / "<url>" is an invalid url.

forwardRequestHistory ​

kotlin
suspend fun forwardRequestHistory(params: JsonObject, fetchOptions: FetchOptions? = null): JsonObject
java
CompletableFuture<Map<String, Object>> forwardRequestHistory(Map<String, ?> params, FetchOptions fetchOptions)
// also forwardRequestHistory(params)

Your forwarded requests to one URL and method. Returns {"list", "startKey", "endOfList", "startKeyHistory"}; see Paging. The server sends up to 100 at a time.

keytype
urlstringRequired, as it was sent.
methodstringRequired, upper case: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD".
statusstring"pending", "running", "resolved" or "failed".
queuestringRequests in queues whose name starts with this.
queue_exactbooleanOnly the queue named in queue.
queue_excludestringLeave out this queue.
compactbooleanLeave the bodies out; give request_text, response_text, response_complete_marker and "compact": true instead.

Each item has id, status_code, response_body and request_id; the other keys are there when the server stored them:

key
idthe short id
status_codethe destination's status code, or null
response_bodythe answer as stored, text (not parsed), or null
errorthe error of a failed request
created, updatedmilliseconds
executedwhen it began running, milliseconds
respondedwhen the answer finished arriving, milliseconds
request_bodythe data or params sent
expireswhen it leaves the history
status"pending", "running", "resolved", "failed" or "cancelled"
queue_name
request_idfor forwardRequestPoll

Errors ​

codemessage
INVALID_PARAMETERKey "url" is required. / Key "method" is required.
INVALID_PARAMETER<value> is invalid in "url". allowed type or value is: Type<string>.
INVALID_PARAMETER<value> is invalid in "method". allowed types or values are: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD".
INVALID_PARAMETER<value> is invalid in "status". allowed types or values are: "pending", "running", "resolved", "failed".
INVALID_PARAMETER<value> is invalid in "compact". allowed type or value is: Type<boolean>. (also "queue_exact")

cancelForwardRequest ​

kotlin
suspend fun cancelForwardRequest(params: JsonObject): JsonElement
java
CompletableFuture<Object> cancelForwardRequest(Map<String, ?> params)

Cancels a request that is still pending or running; it stays in the history as cancelled. A streamed request's pieces are discarded. params: url, method (upper case) and id (the short id), all required.

Returns {"removed": <boolean>, "message": <string>}: Cancelled., Request not found. or The request has already been processed.

Errors ​

codemessage
INVALID_PARAMETERKey "url" is required. / Key "method" is required. / Key "id" is required.
INVALID_PARAMETER<value> is invalid in "method". allowed types or values are: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD".

forwardRequestQueueCount ​

kotlin
suspend fun forwardRequestQueueCount(params: JsonObject): JsonElement
java
CompletableFuture<Object> forwardRequestQueueCount(Map<String, ?> params)

How many requests wait in one queue. Signed-in users only. params: {"queue": <string>}.

Returns {"queue_name": <string>, "in_queue": <number>}.

Errors ​

codemessage
INVALID_PARAMETER"queue" is required.
INVALID_REQUESTUser login is required.

skapi-kotlin 2.4.1