basiq-sdk-golang

README

Basiq.io Golang SDK

This is the documentation for the Golang SDK for Basiq.io API

Introduction

Basiq.io Golang SDK is a set of tools you can use to easily communicate with Basiq API. If you want to get familiar with the API docs, click here.

The SDK is organized to mirror the HTTP API's functionality and hierarchy. The top level object needed for SDKs functionality is the Session object which requires your API key to be instantiated. You can grab your API key on the dashboard.

Changelog

1.0.2 - Documentation updated, added RefreshToken method on the Session object

1.0.1 - Documentation updated

1.0.0 - Supported 2.0 API version

0.9.0beta - Initial release

Getting started

Now that you have your API key, you can use the following command to install the SDK:

go get -u github.com/basiqio/basiq-sdk-golang/

In order to instantiate Session object, following package should be imported:

import (
        "github.com/basiqio/basiq-sdk-golang/basiq"
)

Services for API version 1.0 are located in v1 package:

import (
        "github.com/basiqio/basiq-sdk-golang/v1"
)

Services for API version 2.0 are located in v2 package:

import (
        "github.com/basiqio/basiq-sdk-golang/v2"
)

Common usage examples

Fetching a list of institutions

You can fetch a list of supported financial institutions. The function returns a list of Institution structs.

package main

import (
        "github.com/basiqio/basiq-sdk-golang/basiq"
        "log"
)

func main() {
        session, err := basiq.NewSessionV1("YOUR_API_KEY")
        if err != nil {
            log.Printf("%+v", err)
        }

        institutions, err := session.GetInstitutions()
        if err != nil {
            log.Printf("%+v", err)
        }
}

Fetching institutions v2.0:

package main

import (
        "github.com/basiqio/basiq-sdk-golang/basiq"
        "log"
)

func main() {
        session, err := basiq.NewSessionV2("YOUR_API_KEY")
        if err != nil {
            log.Printf("%+v", err)
        }

        institutions, err := session.GetInstitutions()
        if err != nil {
            log.Printf("%+v", err)
        }
}

Creating a new connection

When a new connection request is made, the server will create a job that will link user's financial institution with your app.

package main

import (
        "github.com/basiqio/basiq-sdk-golang/basiq"
        "log"
)

func main() {
        session, err := basiq.NewSessionV1("YOUR_API_KEY")
        if err != nil {
            log.Printf("%+v", err)
        }

        user := session.ForUser(userId)

        job, err := user.CreateConnection(&services.ConnectionData{
                Institution: &services.InstitutionData{
                    Id: "AU00000",
                },
                LoginId:  "gavinBelson",
                Password: "hooli2018",
        })
        if err != nil {
                log.Printf("%+v", err)
        }

        // Poll our server to wait for the credentials step to be evaluated
        connection, err := job.WaitForCredentials(1000, 60)
        if err != nil {
                log.Printf("%+v", err)
        }
}

Fetching and iterating through transactions

In this example, the function returns a transactions list struct which is filtered by the connection.id property. You can iterate through transactions list by calling Next().

package main

import (
        "github.com/basiqio/basiq-sdk-golang/basiq"
        "log"
)

func main() {
        session, err := basiq.NewSessionV1("YOUR_API_KEY")
        if err != nil {
            log.Printf("%+v", err)
        }

        user := session.ForUser(userId)

        fb := utilities.FilterBuilder{}
        fb.Eq("connection.id", "conn-id-213-id")
        transactions, err := user.GetTransactions(&fb)
        if err != nil {
                log.Printf("%+v", err)
        }

        for {
                next, err := transactions.Next()
                if err != nil {
                    log.Printf("%+v", err)
                    break
                }

                if next == false {
                    break
                }

                log.Println("Next transactions len:", len(transactions.Data))
        }
}

API

The API of the SDK is manipulated using Services and Entities. Different services return different entities, but the mapping is not one to one.

Errors

If an action encounters an error, you will receive an APIError instance. The struct contains all available data which you can use to act accordingly.

APIError struct

type ResponseError struct {
        CorrelationId string `json:"correlationId"`
        Data          []ResponseErrorItem
}

type ResponseErrorItem struct {
        Code   string      `json:"code"`
        Title  string      `json:"title"`
        Detail string      `json:"detail"`
        Source ErrorSource `json:"source"`
}

type APIError struct {
        Data       map[string]interface{}
        Message    string
        Response   ResponseError
        StatusCode int
}

Check the docs for more information about relevant fields in the error object.

Filtering

Some of the methods support adding filters to them. The filters are created using the FilterBuilder struct. After instantiating the struct, you can invoke methods in the form of Comparison(field, value).

Example:

fb := utilities.FilterBuilder{}
fb.Eq("connection.id", "conn-id-213-id").Gt("transaction.postDate", "2018-01-01")
transactions, err := user.GetTransactions(&fb)

This example filter for transactions will match all transactions for the connection with the id of "conn-id-213-id" and that are newer than "2018-01-01". All you have to do is pass its reference when you want to use it.

SDK API List

Services

Session

Creating a new Session object

Version 1.0.

session, err := basiq.NewSessionV1("YOUR_API_KEY")

Version 2.0.

session, err := basiq.NewSessionV2("YOUR_API_KEY")

Refreshing a token

err := session.RefreshToken()

Getting institutions

institutions, err := session.GetInstitutions()

Getting institution

institution, err := session.GetInstitution("INSTITUTION_ID")

Creating a new user

user, err := session.CreateUser(userData)

Referencing a user

Note: The following action will not send an HTTP request, and can be used to perform additional actions for the instantiated user.

user := session.ForUser(userId)

UserService

The following are APIs available for the User service

Creating a new UserService

userService := v1.NewUserService(session)

Version 2.0.

userService := v2.NewUserService(session)

Referencing a user

Note: The following action will not send an HTTP request, and can be used to perform additional actions for the instantiated user.

user := userService.ForUser(userId)

Creating a new User

user, err := userService.CreateUser(&Services.UserData{
        Mobile: "+61410888555",
})

Getting a User

user, err := userService.GetUser(userId)

Update a User

user, err := userService.UpdateUser(userId, &Services.UserData{})

Delete a User

err := userService.DeleteUser(userId)

Refresh connections

err := userService.RefreshAllConnections(userId)

List all connections

conns, err := userService.ListAllConnections(userId, *filter)

Get account

acc, err := userService.GetAccount(userId, accountId)

Get accounts

accs, err := userService.GetAccounts(userId, *filter)

Get transaction

transaction, err := userService.GetTransaction(userId, transactionId)

Get transactions

transactions, err := userService.GetTransactions(userId, *filter)

ConnectionService

The following are APIs available for the Connection service

Creating a new ConnectionService

connService := v1.NewConnectionService(session, user)

Version 2.0.

connService := v2.NewConnectionService(session, user)

Get connection

connection, err := connService.GetConnection(connectionId)

Get connection entity with ID without performing an http request

connection := connService.ForConnection(connectionId)

Create a new connection

job, err := connService.NewConnection(*connectionData)

Update connection

job, err := connService.UpdateConnection(connectionId, password)

Delete connection

err := connService.DeleteConnection(connectionId)

Get a job

job, err := connService.GetJob(jobId)

TransactionService

The following are APIs available for the Transaction service

Creating a new TransactionService

transactionService := v1.NewTransactionService(session)

Version 2.0.

transactionService := v2.NewTransactionService(session)

Get transactions

transactionList, err := transactionService.GetTransactions(userId, *filter)

InstitutionService

The following are APIs available for the Institution service

Creating a new InstitutionService

instService := v1.NewInstitutionService(session, userId)

Version 2.0.

instService := v2.NewInstitutionService(session, userId)

Get institutions

institutions, err := instService.GetInstitutions()

Get institution

institution, err := instService.GetInstitution(institutionId)

Entities

Updating a user instance [mut]

err := user.Update(&Services.UserData{
        Mobile: "+61410888665",
})

Deleting a user

err := user.Delete()

Get all of the user's accounts

accounts, err := user.GetAccounts()

Get a user's single account

account, err := user.GetAccount(accountId)

Get all of the user's transactions

transactions, err := user.GetTransactions()

Get a user's single transaction

transaction, err := user.GetTransaction(transactionId)

Create a new connection

job, err := user.CreateConnection(&services.ConnectionData{
         Institution: &services.InstitutionData{
             Id: "AU00000",
         },
         LoginId:  "gavinBelson",
         Password: "hooli2018",
})

Refresh all connections

err := user.RefreshAllConnections()

Connection

Refresh a connection

job, err := connection.Refresh()

Update a connection

job, err := connection.Update(password)

Delete a connection

err := connection.Delete()

Job

Get the connection id (if available)

connectionId := job.GetConnectionId()

Get the connection

connection, err := job.GetConnection()

Get the connection after waiting for credentials step resolution

(interval is in milliseconds, timeout is in seconds)

connection, err := job.WaitForCredentials(interval, timeout)

Get the connection after waiting for transactions step resolution

(interval is in milliseconds, timeout is in seconds)

connection, err := job.WaitForTransactions(interval, timeout)

Transaction list

Getting the next set of transactions [mut]

next, err := transactions.Next()

Documentation

Overview

Official BASIQ SDK for the Go programming language.