Skip to content

Tickets ​

Every method throws SkapiException with a code and a message, and can throw NETWORK_ERROR when no answer comes back. All of them are suspend functions of Skapi. See Tickets.

consumeTicket ​

kotlin
suspend fun consumeTicket(ticketId: String, method: String = "POST", data: JsonElement? = null, auth: Boolean = false): JsonElement
java
CompletableFuture<Object> consumeTicket(String ticketId, String method, Object data, boolean auth)  // method ("POST"), data and auth (false) can be left out

Calls a ticket of the project, at https://<first 4 characters of the service ID>.skapi.dev/.

argument
ticketIdLetters, digits, _ and -, up to 64 characters, starting with a letter or digit.
method"GET" or "POST", any case. GET sends data as the query string (/tg/ route); POST sends it as the JSON body (/tp/ route).
dataThe request data, usually a JsonObject. Defaults to {}.
authtrue sends the call as the signed-in user (POST /tpa/ route, with the user's token). POST only.

Returns the receipt, or the body a Respond action of the ticket composed, as sent:

key
ticket_idthe ticket
consume_idbase62 of the time in milliseconds, then 4 random characters
user_idthe user with auth = true, else "<ip>(<user agent>)"
is_testfalse
timestampmilliseconds, read from consume_id
hashproof string of the consumption
queuedtrue only when the call waits for a free slot; its actions run later
positionwith queued: place in the line, 1 = next

Errors ​

codemessage
INVALID_PARAMETERTicket ID is required.
INVALID_PARAMETERInvalid "ticket_id". Use letters, digits, "_" and "-" (up to 64 chars, starting with a letter or digit).
INVALID_PARAMETERMethod is required. Should be either "GET" or "POST"
INVALID_PARAMETERMethod should be either "GET" or "POST".
INVALID_PARAMETERSigned-in consumption is POST only.
INVALID_REQUESTUser login is required. (auth = true, signed out)
TICKET_BUSYevery slot of a ticket with a concurrency limit is taken. Nothing was consumed; try again later. details carries {"concurrency", "running", "waiting", "self_calling"}.
the ticket's codethe ticket's message. details is the whole error body: {"code", "message", "stage", "action"?, "detail"?, "ticket_id"}. Thrown whether the ticket answered 400 or 200. See When a consumption fails.

getTickets ​

kotlin
suspend fun getTickets(params: JsonObject? = null, fetchOptions: FetchOptions? = null): JsonObject
java
CompletableFuture<Map<String, Object>> getTickets(Map<String, ?> params, FetchOptions fetchOptions)  // params and fetchOptions can be left out

The project's tickets. Signed-in users only. Returns {"list", "startKey", "endOfList", "startKeyHistory"}, up to 100 a page; see Paging.

keytype
ticket_idstringOnly this ticket.

Each row:

key
ticket_id
description
countconsumptions left, when the ticket has a count
time_to_livewhen it expires, milliseconds, when it has one
timestampwhen it was registered, milliseconds

Errors ​

codemessage
INVALID_REQUESTUser login is required.
INVALID_REQUESTInvalid ticket id. (ticket_id contains # or @)

getConsumedTickets ​

kotlin
suspend fun getConsumedTickets(params: JsonObject? = null, fetchOptions: FetchOptions? = null): JsonObject
java
CompletableFuture<Map<String, Object>> getConsumedTickets(Map<String, ?> params, FetchOptions fetchOptions)  // params and fetchOptions can be left out

The signed-in user's own consumptions, the ones made with auth = true, oldest first. Returns {"list", "startKey", "endOfList", "startKeyHistory"}.

keytype
ticket_idstringOnly tickets whose ID starts with this.

Each row:

key
ticket_id, consume_id, timestampas in the receipt
user_id, regthe user's ID
is_testfalse (dry runs are anonymous, so they never appear here)
descriptionthe consumption log as JSON text, with data, method, headers, ip, user_agent, timestamp and outcome (ok, actions, error, ...)
hashproof string of the consumption

Errors ​

codemessage
INVALID_REQUESTUser login is required.

skapi-kotlin 2.4.1