Accessing the Kiva Api with Visual Basic

Kiva list a Dot Net Api class in C# so writing your own in Visual Basic is a tat obsolete were it not that I already had a complete database to process the data dump and I wanted a basic API class that only consumes XML and exposes it as a DataSet to update the main database, and add more user-oriented functionality, so I wrote a quick basic API-client. There, I said it.

The example project is on the server :  KivaVBLibrary Kiva Api example in VB (coded in Visual Basic Express 2010)

About the API

The Kiva API is a HTTP Rest API  using Basic HTTP Auth. I noticed Kiva do not check on credentials on the function I list below here, but I included a basic http authentication anyway. I do expect Kiva to switch to using OAuth somewhere along the line, but for now it is Basic HTTP Auth.

Rate limiting and TOS

Kiva allow 60 calls per minute for unregistered and 500 calls a minute per registered account, Kiva terms are general but Kiva emphasize you should respect the privacy of site users and not misrepresent the data.

The sample

On with the sample, I am going to make a Visual Basic Class to access the Kiva API, retrieve an XML response file, load that into a DataSet object and retrieve and display the data from the DataSet object on a Form.

I took the UrlFactory Class from the Kiva Api Library C# example, and recoded part of it in Visual Basic, one class URLFactory to compose the URL’s accor :

Namespace KivaVBLibrary

    Public Class URLFactory

        Public baseURL As String = "http://api.kivaws.org/v1/"
        Public urlSuffix As String = ".xml"
        //The API returns either html, xml or json depending on the suffix you send in the url.

        Public Function GetLenderURL(ByVal UID As String) As String
            Return baseURL + "lenders/" + UID + urlSuffix
        End Function
    End Class
End NameSpace

With that URL available, let’s get some XML, in this case the basic lender record of Matt (one of the co founders of kiva), retrieved from //api.kivaws.org/v1/lenders/matt.xml

The GetLender function of the KivaAPI class gets the XML data from the API and returns it as Dataset :

Imports System.Net
Imports System.Text

Namespace KivaVBLibrary

Public Class KivaAPI

    Private _UrlFactory As New KivaVBLibrary.URLFactory

    Private _AppID As String = "org.juust.kivareader"
    Private _UserAgent As String = "KivaReader (https://www.juust.org) appid:" & _AppID

    Private _userName As String = ""
    Private _userPassword As String = ""

    Public Property AppID As String
        Get
            Return _AppID
        End Get
        Set(ByVal value As String)
            _AppID = value
        End Set
    End Property

    Public Property userName As String
        Get
            Return _userName
        End Get
        Set(ByVal value As String)
            _userName = value
        End Set
    End Property

    Public Property userPassword As String
        Get
            Return _userPassword
        End Get
        Set(ByVal value As String)
            _userPassword = value
        End Set
    End Property

    Public Sub New()
    End Sub

    Public Sub SetBasicAuthHeader(ByVal request As HttpWebRequest)

        Dim authInfo As String = Me.userName + ":" + Me.userPassword
        authInfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo))
        With request
            .Headers("Authorization") = "Basic " + authInfo
            .Accept = "application/xml"
            .UserAgent = "KivaReader 1.0.0.0 (juust.org)"
            .AllowAutoRedirect = False
            .Timeout = 5000
            .KeepAlive = False
        End With
    End Sub

    Public Function GetLender(ByVal LenderID As String) As DataSet

        Dim MyRequest As HttpWebRequest

        MyRequest = HttpWebRequest.Create(_UrlFactory.GetLenderURL(LenderID))
        With MyRequest
            .Method = "GET"
        End With

        SetBasicAuthHeader(MyRequest)

        Dim DataSetLender As DataSet
        DataSetLender = New DataSet()
        Using MyResponse As HttpWebResponse = MyRequest.GetResponse()
            DataSetLender.ReadXml(MyResponse.GetResponseStream())
        End Using
        MyRequest = Nothing

        Return DataSetLender

    End Function

End Class
End NameSpace

Now we have the code to retrieve the DataSet object from the Kiva API, so let’s make a quick Form, with three texboxes (username, password and the id of the lender you want to retrieve data for), two rich format boxes to display data from the dataset and a button to run the API Test :

…and in the form module we add some basic code that creates an instance of KivaVBLibrary.KivaAPI, sets our basic authorization, and calls the GetLender function to retrieve the Lender data for the ID we fill in in the form :

Public Class Form1

    Private myApi As New KivaVBLibrary.KivaAPI

    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btntestApi.Click
        myApi.userName = TxtUsername.Text
        myApi.userPassword = TxtPassword.Text

        Dim ds As DataSet
        ds = myApi.GetLender(TxtLender.Text)

        PrintDataRecords(ds)
        PrintDataSet(ds)

    End Sub

Click the button on the form, and after a second, we get our first data :

The Dataset is processed twice, one for general Table set data, and one for the content using the two rich text boxes (RtLender and RTTableSet) to display data on the form :

   Public Sub PrintDataRecords(ByVal ds As DataSet)

        // Print out all tables and their columns
        Dim iRow As DataRow
        Dim iCol As DataColumn
        For Each table As DataTable In ds.Tables
            For Each iRow In table.Rows
                For Each iCol In table.Columns
                    RTLender.AppendText(iCol.ToString)
                    RTLender.AppendText(vbTab & iRow(iCol.ToString).ToString)
                    RTLender.AppendText(vbCrLf)
                Next
            Next
        Next  // For Each table  

    End Sub

    Public Sub PrintDataSet(ByVal ds As DataSet)

        // Print out all tables and their columns
        For Each table As DataTable In ds.Tables
            RTTableSet.AppendText(vbCrLf & "TABLE " & table.TableName)
            RTTableSet.AppendText(vbCrLf & "Total # of rows: " & table.Rows.Count)
            RTTableSet.AppendText(vbCrLf & "---------------------------------------------------------------")

            For Each column As DataColumn In table.Columns
                RTTableSet.AppendText(vbCrLf & column.ColumnName & " " & column.DataType.ToString())
            Next  // For Each column
            RTTableSet.AppendText(vbCrLf)

        Next  // For Each table  

        // Print out table relations
        For Each relation As DataRelation In ds.Relations
            RTTableSet.AppendText(vbCrLf & "RELATION: " & relation.RelationName)
            RTTableSet.AppendText(vbCrLf & "---------------------------------------------------------------")
            RTTableSet.AppendText(vbCrLf & "Parent: " & relation.ParentTable.TableName)
            RTTableSet.AppendText(vbCrLf & "Child: " & relation.ChildTable.TableName)
            RTTableSet.AppendText(vbCrLf)
        Next  // For Each relation  

    End Sub

さよなら (=goodbye)

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top