Skip to content

Usage

After the SDK is initialized you can obtain an instance of it by calling BittiqSdk.getInstance(). For the available methods in the sdk see the BittiqSdk class. Each method returns a BittiqTask object which can be used to either execute the task synchronously or asynchronously.

Synchronous execution

When you manage your own threading (ie. with RxJava) it's recommended to make use of synchronous execution. There is a method executeAwait() inside the BittiqTask which is a blocking method. It returns a Result object, see below for more information.

Asynchronous execution

When you want to use the sdk from the main thread it's recommended to make use of asynchronous execution. There is a method execute() inside the BittiqTask which accepts a callback. When this callback is invoked, it will give you a Result object. See below for more information.

Result

After executing a Bittiq call, a Result is returned either as return value in case of a synchronous call or through a callback when the method was asynchronously executed. This object is either of type Result.Success when the call was successful or Result.Failure when an error occurred processing the method.

Result Success

The Result.Success has a value property which contains the data model.

Result Failure

The Result.Failure has an error property which contains the exception that occurred during execution. These exceptions can be categorized as follow:

  • BittiqException is the generic exception where all other exceptions inherit from.
  • BittiqApiNotAvailableException occurs when the api is unavailable. This issue might be resolved a few seconds later so it's best practice to give the user the opportunity to retry the request.
  • BittiqClientException occurs when there's an error in the request. Inspect the error code to find out the specific cause:
    • auth_access_denied - Unauthorized to perform request. This will also be returned when the TokenResolver isn't able to provide the sdk with an access and refresh token.
    • resource_not_found - When the requested resource couldn't be found.
  • BittiqNetworkException occurs when there's a problem talking to the server. This exception also happens when an in-flight request is canceled.
  • BittiqRuntimeException if an unexpected error occurs creating the request or processing the response. This exception can't be resolved by the user and should be reported to Bittiq to be resolved.
  • BittiqInputValidationException if request parameters are invalid. The exception contains a map with the validation errors that occurred.
  • BittiqPrerequisiteException when a BittiqTask is executed but a prerequisite is not met. Utilize the documentation of the method throwing this exception to understand it's usage.

Pagination

Some SDK calls return a paginated response, in the form of a PagedData object. This object contains a cursor to the previous result set (if available), a cursor to the next result set (if available) and the items for the current result set.

Calls that return a paginated response will also support a cursor parameter for which you can supply either the cursor for the previous or next result set. An example of a paginated call is getTransactions.

Sample

val sdk = BittiqSdk.getInstance()

// Get providers asynchronously
sdk.getProviders().execute {
    when (it) {
        is Result.Success -> handleSuccess(it.value)
        is Result.Failure -> handleFailure(it.error)
    }
}