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)