Skip to content

API Bridge ​

Every method raises SkapiError with a code and a message. Values that fail a check raise INVALID_PARAMETER before anything is sent. Any method can raise NETWORK_ERROR when no answer comes back. 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.).

forward_request ​

python
skapi.forward_request(options: dict, form: dict | None = None, *, on_stream: Callable[[str, int], None] | None = None) -> Any

Calls another API from Skapi's server.

argument
optionsRequired. Keys below.
formdict merged into data, or into params for GET, DELETE and HEAD; an option's own key wins. With multipart, the multipart body.
on_stream(text, seq), called with each relayed piece of a streamed request, in order. Exceptions it raises are ignored.
option keytype
urlstrRequired. A full URL.
methodstr"GET", "POST" (default), "PUT", "PATCH", "DELETE", "HEAD", any case.
headersdictNo name starting with x-skapi-.
datadictThe body: JSON when Content-Type is application/json, form-encoded otherwise.
paramsdictThe query string.
secretNamestrA 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.
skapiHeadersbool or {"user"?: bool, "service"?: bool}Sends x-skapi-user (the signed-in user's ID) and x-skapi-service.
queuestrQueue the request on the server. No colons.
pollint, float or boolMilliseconds between checks (True = 1000). Waits for the answer; makes a queue name when none is given.
streamboolRelay the answer as it arrives. Queued and polled like poll.
expiresintSeconds the request stays in the history after it settles.
multipartboolSend form as multipart/form-data. Files are {"file", "filename"?, "content_type"?} dicts or bytes.
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).

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 forward_request_poll returns once the request settles.

Errors ​

codemessage
INVALID_PARAMETER"options" is required in the second argument.
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. / "form" should be a submit event, a form element, FormData, or an object.
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 raised: inline it is returned as the answer, queued it is the failed result below.

forward_request_poll ​

python
skapi.forward_request_poll(request_id: str, *, poll: float = 1000, url: str | None = None, method: str | None = None,
                           on_stream: Callable[[str, int], None] | None = None) -> Any

Waits for a queued request and returns its result. The first check goes out after poll milliseconds (0 means 1000). It blocks until the request settles; there is no time limit. With on_stream, new text of a streamed request is handed over as it arrives.

argument
request_idThe request_id, or the short id with url and method.
pollMilliseconds between checks.
url, methodNeeded with a short id.
on_stream(text, seq) for a streamed request.

Returns:

the requestreturns
resolvedthe destination's answer (or the finalized value of a streamed request)
failed{"status_code": int, "body": str, "truncated": ...}, or another error dict 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 on_stream

Errors ​

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

forward_request_stream ​

python
skapi.forward_request_stream(request_id: str, options: dict | None = None, *,
                             on_stream: Callable[[str, int], None] | None = None) -> Any

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 on_stream 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, methodstrNeeded with a short id.
sinceintStart after this seq.
pollint or floatMilliseconds 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.

forward_request_finalize ​

python
skapi.forward_request_finalize(request_id: str, data: Any = None, options: dict | None = None) -> dict

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

Returns {"finalized": bool, "message": str}. These come back with finalized: False instead of raising:

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.

forward_request_history ​

python
skapi.forward_request_history(params: dict, fetch_options: dict | None = None) -> dict

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
urlstrRequired, as it was sent.
methodstrRequired, upper case: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD".
statusstr"pending", "running", "resolved" or "failed".
queuestrRequests in queues whose name starts with this.
queue_exactboolOnly the queue named in queue.
queue_excludestrLeave out this queue.
compactboolLeave 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 None
response_bodythe answer as stored, text (not parsed), or None
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 forward_request_poll

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")

cancel_forward_request ​

python
skapi.cancel_forward_request(params: dict) -> dict

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": bool, "message": str}: 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".

forward_request_queue_count ​

python
skapi.forward_request_queue_count(params: dict) -> dict

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

Returns {"queue_name": str, "in_queue": int}.

Errors ​

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

skapi-py 2.4.0