Using the Koha API with C#

I’ve been tinkering with the Koha API to allow MarcEdit to do some direct ILS integration with Koha-based systems.  When I first agreed to look at doing this work, I wasn’t sure what the API looked like.  Fortunately for me, the folks that put it together made it simple and easy to work with.  There are a few gocha’s when working with C#, and while I’ll be posting the source code for the Koha library that I’ve developed in C# on my github account, I thought I’d post some of my initial notes for those that are interested.

Essentially, to work with the Koha API, there are two things that you need to have.  First, you need to authenticate yourself.  Upon authentication, Koha provides session data that is maintained as a cookie that must be passed as part of future requests to the API.  Generally, this process is straightforward, in that you create a cookiejar.  In C#, this looks like the following:

private bool Authorize()
        {
            HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(var_host + "/cgi-bin/koha/svc/authentication?userid=" + var_user + "&password=" + var_pass);
            request.CookieContainer = cookieJar;

            HttpWebResponse response = (HttpWebResponse)request.GetResponse();

            System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream(), Encoding.UTF8);
            string tmp = reader.ReadToEnd();

            //Add cookies to CookieJar (Cookie Container)
            foreach (Cookie cookie in response.Cookies)
            {
                cookieJar.Add(new Cookie(cookie.Name.Trim(), cookie.Value.Trim(), cookie.Path, cookie.Domain));
            }

            reader.Close();
            response.Close();

            if (tmp.IndexOf("ok") > -1)
            {
                return true;
            }
            else
            {
                return false;
            }
            
	}

The Cookie Jar in this case is scoped as global to the class, this way the session information doesn’t need to be regenerated unless the session expires.

Retrieving individual records is supported by the API. 

private string GetRecord(string id)
        {
            string uri = var_host + "/cgi-bin/koha/svc/bib/" + id + "?userid=" + var_user + "&password=" + var_pass;
            HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);
            request.CookieContainer = cookieJar;

            HttpWebResponse response = (HttpWebResponse)request.GetResponse();

            System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream(), Encoding.UTF8);
            string tmp = reader.ReadToEnd();
            
            reader.Close();
            response.Close();

            return tmp;
        }

In the case of Koha, the GetRecord function returns data in MARCXML format. This is my preferred method for retrieving data, but for general search and retrieval, while Koha supports SRU, the most reliable search API is still Z39.50 (sadly).

Finally, when you want to update or create a new record, you need to push the data up to the server in MARCXML format.  If the data is an update, you pass a record id, if it’s a new record, you don’t.

private bool UpdateRecord(string rec) 
	{
   	     return UpdateRecord(rec, null);
	}

private bool UpdateRecord(string rec, string id)
        {
            string uri = "";
 	    if (id == null) {
                uri = var_host + "/cgi-bin/koha/svc/new_bib?userid=" + var_user + "&password=" + var_pass;
            } else {
  	        uri = var_host + "/cgi-bin/koha/svc/bib/" + id + "?userid=" + var_user + "&password=" + var_pass;
 	    }
            HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);
            request.CookieContainer = cookieJar;
            request.Method = "POST";
            request.ContentType = @"text/xml";
            System.IO.StreamWriter writer = new System.IO.StreamWriter(request.GetRequestStream(), System.Text.Encoding.UTF8);
            writer.Write(rec);
            writer.Flush();
            writer.Close();
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();

            System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream(), Encoding.UTF8);
            string tmp = reader.ReadToEnd();

            reader.Close();
            response.Close();

            return true;

        }

And that’s pretty much it. Simple and straightforward. Koha supports a few more API (http://wiki.koha-community.org/wiki/Koha_/svc/_HTTP_API, but for my immediate purposes, these are the couple that I need to support some very simple integration with the ILS. Ideally, at some point, it would be nice to see these API also support automated deletion of records, as well as maybe an ability to set holdings/items — but for now, this is good enough. I’m sure if these other functions are needed, the communities themselves will push for them within their own user communities and when they show up, MarcEdit will indirectly benefit.

–TR