What each call of the SDK returns
PHPThe objects the calls of the SDK return — an execution, its trace, a customer, an account, an entry of the statement, a page — and which field of the answer of the API each of their fields carries.
A call of the SDK returns an object that carries the answer of the API. This page names the object each call returns and says which field of the answer each of its fields is.
How a result is shaped
A result is an object whose properties cannot be changed. It has a property for each field of the answer, named in camel case. An amount of money or of credits is a decimal string, never a float; an id is a string; a time is a DateTimeImmutable; a status is an enum — ExecutionStatus, CustomerStatus, CreditEntryType. An answer that lacks a field, or carries a value of another type, raises InvalidResponseException instead of a result with a default in its place.
Which call returns what
| Result | Returned by |
|---|---|
ExecutionDTO | operations()->execute(), operations()->executeAsync() |
ExecutionStatusDTO | executions()->get(), executions()->wait() |
ExecutionTraceDTO | executions()->trace() |
CustomerDTO | customers()->get(), customers()->create(), customers()->block(), customers()->unblock() |
CustomerAccountDTO | customers()->updateAccount(), customers()->topUp(), customers()->charge(), customers()->adjust() |
CustomerPageDTO | customers()->list() |
CreditEntryPageDTO | customers()->entries() |
A list of CreditPriceDTO | customers()->prices() |
HealthDTO | health() |
customers.delete() returns nothing. The events of a webhook are described in Webhooks.
An execution
Send a request describes each field of an execution.
| Property | The field of the answer |
|---|---|
executionId | execution_id |
status | status, as ExecutionStatus |
operationCode | operation |
output | output |
errorCode | error_code |
errorMessage | error_message |
error | error, as ExecutionErrorDTO with code and message |
cost | cost, as ExecutionCostDTO with estimated and actual |
cache | cache, as ExecutionCacheDTO with hit and cachedAt |
waitingOn | waiting_on, as WaitingOnDTO with nodeKey, type and resumeAt |
traceUrl | trace_url |
retryAfterSeconds | retry_after_seconds |
replayed | replayed |
ExecutionStatusDTO, the same execution read later, has every property but error and replayed. Both have four methods that read the status: isCompleted(), isRejected(), isPending() — the execution is queued, waiting or running — and isFinished(), which is true when it is none of these.
The trace of an execution
ExecutionTraceDTO is the execution with nodes — every node it passed, in order, each a TraceNodeDTO with its attempts at the providers — and events, the events of its trace, each a TraceEventDTO. The type of a node, its status and the type of an event stay strings: a later version of Slen may add new ones.
The fields are those of GET /v1/executions/{id} on Executions.
A customer and an account
Customers and credits says what a customer and an account are for.
Property of CustomerDTO | The field of the answer |
|---|---|
customerId | customer_id |
externalUserId | external_user_id |
status | status, as CustomerStatus |
blockedAt | blocked_at |
blockReason | block_reason |
accounts | accounts, each a CustomerAccountDTO |
createdAt | created_at |
updatedAt | updated_at |
CustomerDTO::isBlocked() reads the status, and CustomerDTO::account() gives the account of one credit type, or null when the customer has none of that type.
Property of CustomerAccountDTO | The field of the answer |
|---|---|
customerAccountId | customer_account_id |
customerId | customer_id |
projectId | project_id |
externalUserId | external_user_id |
creditType | credit_type |
balance | balance |
reserved | reserved |
available | available |
allowNegative | allow_negative |
lowBalanceThreshold | low_balance_threshold |
createdAt | created_at |
updatedAt | updated_at |
The fields are those of GET /v1/customers/{externalUserId} on Customers and credits.
The statement and the prices
CreditEntryDTO is one movement of the statement: entryId, customerAccountId, externalUserId, creditType, entryType — a CreditEntryType — credits with a sign, balanceAfter, availableAfter, reservationId, note and createdAt. CreditPriceDTO is the price of one operation in one credit type: creditPriceId, projectId, operationCode, creditType, credits, createdAt and updatedAt.
A page
PageDTO has data, the rows of the page, and nextCursor — the cursor of the next page. hasMore() is true while there is a cursor.
Pass the cursor to the next call, and stop when it is null. A full last page may still carry a cursor; the page after it is then empty.
Where to go next
Client and methods — every call of the SDK, with the request it makes.
Send a request — every field of an execution.
Handling errors — what a call raises instead of returning.