Thursday, November 08, 2007

API Wrapper Classes

The past couple of days I have been on a short course run by one of our vendors about using the API from one of there products.

Now I have to firstly applaud them for making there product open enough for us to call it using its api, there are some bits of business logic missing, but for the most part it is very good and very well documented.

The only problem with it is the amount of parameters you can pass to some of the methods, and the amount of information you get back. In some case's there are over 30 inputs to a method, but only 2 are mandatory. So Calling the API could look something like this:

result = AppInteraction.API("APICustSearch", pi_pointer, pi_source, type.missing, type.missing, type.missing) etc etc

This kind of code while functional can get very messy and hard to read. What we could do with is a class to wrap the functionality of the API calls in.

First thing to do is create a couple of classes for the input and outputs of the method. This example is using the method called APICustSearch, it will have 5 possible inputs and 3 outputs.

Public Class CustSearch _input
Public Spointer As String

Public Source As String

Public date As String

Public Active As String
Public MinSpend As String

End Class


Public Class CustSearch _results
Public Result As Integer

Public Resulttext As String

Public Custname As String

End Class


The above classes just deal with the inputs/outputs of the api, next we need to code the actual api call into a class:

Public Class AppWrapper
' Defintion for API APICustSearch
Public Function CustSearch(ByVal oInput As CustSearch_input) As CustSearch_results

Dim oApp As New AppAPI.Interaction
Dim oResults As New AppAPI.colGeneric
Dim oReturn As New Suborderrestart_results

oResults = oApp.API("APICustSearch", oInput.Spointer , oInput.Source, oInput.date, oInput.Active, oInput.MinSpend )

While System.Runtime.InteropServices.Marshal.ReleaseComObject(oApp) > 0
End While
While System.Runtime.InteropServices.Marshal.ReleaseComObject(oResults) > 0
End While

oResults = Nothing
oApp = Nothing

Return oReturn
End Function

End Class


So now we have our class to call the functionality of the API method we are interested in, we can easily call it from our application like so:

Dim App As New AppWrapper
Dim CustSearchParam As New CustSearch_input
Dim search_result As CustSearch_results

With CustSearchParam
.Spointer = "12345"
.Source = "API"
.date = "08/11/2007"
.Active = "Y"
.MinSpend = "0"
End With


search_result = App.CustSearch(CustSearchParam)

'this is some checking specific to the API i was working with. If the search_result.Result was not 0
'an error had happened and the details were in search_result.Resulttext
If (search_result.Result <> 0) Then
MessageBox.Show(search_result.Resulttext, "Search error")
End If

If (search_result.Result = 0) Then
MessageBox.Show(search_result.Resulttext, "SubOrderRestart Suceeded" & vbnewline & search_result.Custname )
End If

You will obviously have to tailor the classes based on the api you are using, but you can just add all the methods you use the the AppWrapper class, and create new input and output classes based on the spec.

Apologies for any errors in the example code, I have re-written sections of mine to make it more generic, but hopefully you should get the idea

No comments: