Friday, June 5, 2009

The API Explorer

EKP provides an application programming interface (API) that enables other applications and Web sites to interact with EKP—for example, to create user accounts and enrollments, and to obtain information about courses, catalogs, enrollments and training records.

We've always provided API documentation as part of the EKP distribution. However, in working with software developers, we've identified a couple of ways in which the documentation could be improved.

Firstly, the API changes between releases as new API functions are added. This means it's important to work with the correct version of the documentation for the EKP version you're developing for. However, keeping track of different document versions is a hassle.

Secondly, most developers learn more easily if they are able to call API functions interactively and generate actual responses, rather than simply reading dry documentation. However, calling API functions generally involves writing code.

With these points in mind, in EKP 5.6 we introduced the API Explorer. The API Explorer serves two purposes: it is both an online reference for the API functions, and a tool that enables developers to learn about the API by calling its functions interactively.

Enterprise Knowledge Platform API

The API Explorer lists the API functions available. For each function, it provides information about how to invoke the function, including the URL and the expected HTTP method, parameters and authentication scheme. Where possible, it provides one or more HTML forms that can be used to call the API function directly from the browser. (Note: some API functions cannot be invoked from a browser.)

userNews API function

The API Explorer can be accessed by appending api/ to the base URL of your EKP site. For example, if your site is located at http://www.example.com/ekp/, then the API Explorer for the site can be accessed at http://www.example.com/ekp/api/. At the time of writing, an instance of the API Explorer is available at http://utest2.netdimensions.com/utest/api/.

Note: If you do not see the API Explorer at the expected URL, your Web server (e.g. Apache or IIS) might not be forwarding the requests to Tomcat. In the case of Apache, you can fix this by adding a directive like the one below to httpd.conf.

JkMount /ekp/api/* ajp13

1 comment:

Jim Johnson said...

This is pretty slick, Rob. Glad Net D added this.