ARCHIVED: KB web services: Using SOAP

• Prerequisites
• Getting set up
• Testing
• Example code
• Errors

Prerequisites

You will need a SOAP key before you can begin using SOAP. You must pass this key in as an argument to every SOAP call you make, or the server will reject your request. This documentation refers to the SOAP key as string authKey. If you do not yet have a SOAP key, send a request to kbmisc@indiana.edu .

Getting set up

A WSDL file describes the KB SOAP interface. Many SOAP frameworks will allow you to instantiate an object from this URL and call the provided methods from that object. As such, this URL may be all you need to get started. If not, the details provided in the WSDL file and the rest of this documentation should help you fill in the blanks.

Testing

The SOAP interface provides a special method to help test connections:

string helloWorld(string authKey)

Returns a string: "Hello, authKey, you're in the bathtub!" authKey will be replaced with your SOAP key. You can use this function to test whether or not your SOAP framework is working properly; you should not call it from production code.

Example code

The Knowledge Management System team has written a small set of Perl scripts to demonstrate use of KB web services with SOAP. These scripts use many of the features of the service, and are written to be as clear as possible. You can refer to these to learn the basics and get ideas about how to use the KB web services in your own code.

Errors

When the server encounters an error, it will generate a fault, and the fault string will have detailed information about what went wrong. Fault strings have two parts: an exception class name and an error message. These are separated by a colon and a space. For instance, here are two example fault strings:

  Experimental::Exception::Die: EXCEPTION: Invalid document identifier, wwqz
  BadIDFormat: 123

In the first string, the exception class is Experimental::Exception::Die; the rest of the string, starting with EXCEPTION, is the error message. In the second string, BadIDFormat is the exception class, and 123 is the error message. The rest of the web services documentation explains errors like this alongside the functions that generate them.