APIs – useful tool or business asset?

I’ve recently been working on maintaining an interface between two companies. As part of the maintenance involves tracking down issues to help the developer and hopefully find fixes for them. The API isn’t public and this post is about why I think that the accountancy package should at least document their API publicly.
First, a bit of history of the package’s business model. The company which own the accountancy package sells partnerships to 3rd party suppliers. These 3rd party suppliers then sell the software licences and support to end users (small and medium sized businesses).

The business I work with outsources it’s development. They outsource their development to one of these 3rd party suppliers. It makes a lot of sense for them, they get quality developers who understand their system. The developers who work on similar systems on a day to day basis.

The source code the developers provide is closed source – we just get the binaries. As a Linux user I don’t find this ideal but I understand why they do it from a business point of view. A lot of the package uses JavaScript for limited scripting usage.

When we have issues with one of these pieces of JavaScript we can look though it and find the issue without having to wait for the developer to find, research and look at the issue.

However, the JavaScript which is used also uses libraries provided by the software package. The documentation for these libraries are not publicly available. In fact, no information about them is publicly available.

The API which the package uses is NOT public. Even though we can see some of the scripts which have been written (JavaScript + API) we can’t always accurately make guesses about what is going on within the code. When we encounter (sometimes very serious) errors we can’t always track down these errors because we have to guess what the function actually does.

To me, having a public API makes sense, It means we can more accurately track down issues without having to bother the developer for simple fixes (even though we still check that our change makes sense with them).

The main reason that the API is not available is because the original software developers sell access to it with their developer training. A full developer training course is simply over the top for such a requirement!

SupyBot: A half-ranty review

I’ve recently been playing with SupyBot (an IRC bot written in python) again. It’s main ‘selling points’ are that it aims to be easy to develop plug-ins for. Yeah Right. While I’ve used SupyBot for a long time now (since the start of #unity-coders in fact). I really appreciate both the project and what the developers are doing but I wanted to outline some of the problems I’ve encountered when trying to use SupyBot.

Scripts, Tutorials and Design

There things that SupyBot does really well.The automated scripts for creating bots & plug-ins, the tutorials in the /docs/ folder and the way in which plug-ins are loaded into the core are the three main reasons I’m still using SupyBot. These things combined make writing very simple plug ins virtually effortless. It doesn’t need you to open up random telnet ports to administer the bot either, unlike some other IRC bots. I can’t fault SupyBot on any of these features.

API Documentation

While the scripts that SupyBot ships with to automate plug-in creation are very helpful, they don’t make up for poor documentation. And if there is one thing lacking with SupyBot it’s documentation. Most of the code is documented if you have time to look though all of the project’s source code. I don’t. You’d be better off using the documentation to prop up a table than write a plug-in with.

The closet thing I’ve found to good API documentation is looking at the existing plug-ins shipped with the bot. Which is fine if your plug-in does things which other people’s plug-ins do (or at least partly do). If your plug-in does something a bit different, or the examples are outdated you’ve got no hope, so you better get reading though the source now. The first major thing that I feel the project could benefit from is API documentation.

On a slight sidenode…

I’d also like a list of things I’m not meant to do… I overrode the python equivalent of a constructor (__init__) on a plug-in class and got a small essay from my bot when I loaded the plug-in about a switch from CVS to Darcs and the arguments my constructor should take. While I found this slightly amusing, it really didn’t help very much. It may just be me, but a language that lets you define the value of constants, such as ‘True’ (true story, try it in python 2.x), I really like knowing what I’m allowed to do… because the language won’t stop me from messing up.

Permissions

A lot of the plug-ins also make use of the bot’s permissions system. SupyBot’s permissions system is a very complete and powerful one (even if not very scalable for large groups of users or plug-ins).

Firstly, a brief description of the system. It’s permissions based. The permissions are defined per user. Each command can have a permission in order to use it. The bot uses ‘anti-permissions’ to disallow users using certain commands. Plug-ins seem to be able to define their own additional permissions as well. The system supports a limited form of predefined ‘roles’ (Owner, Admin & Channel Op are the three I’ve used), but I’ve got no idea if you can define your own roles or assign permissions to existing roles.

There is no definitive list of permissions. While I can understand this is a technical limitation of the design, a list of permissions provided with core plug-ins would be helpful to say the least. Even a text file detailing the permissions and what they do would do. You can give a user channel operator privileges using the permission ‘#channel,op’. This is covered in the documentation however what is not covered is what this does. Does it mean the bot will let them have op? change the topic though the bot? order pizza? who knows.

Setting default permissions is also not covered. Can you set permissions for unregistered users? It’s mentioned briefly in a few of the tutorials but not actually documented anywhere! The use case is quite simple, you might want to set the default of a permission to be the ‘anti-permission’ and only allow some users to use the command (checking the system daemon status, for example).

Again trying to use permissions in plug-ins isn’t really covered in any level of detail. It is possible to work it out from existing plug-ins or examining the permission modules’s source code but I’d really rather not do that. The second thing which I would like to recommend for the developers is Permission Documentation (and not letting ops order pizza)*.

Configuration

This last point of my rant is purely from an administrator point of view. Configuration of plug-ins is both a fantastic thing and bad thing in SupyBot. The fact that you can find out what configuration options are available for a plug-in, and get a description over IRC is a really nice feature. It means you don’t have to edit configuration files if you don’t want to and can allow trusted users to make configuration changes in your absence.

However, sometimes having to do searches though the bot interface for the configuration options is a little tiresome. The values which the plug-in expects are not always made clear in these descriptions either (do I set this value to -1 or 0 to disable it? is 0 off or unlimited?). There used to be online documentation for a number of the plugins, detailing their commands and their configuration options. It was removed for being too out of date but you can still find it if you look around.

End user documentation (!help and !list)

When using the bot the user can ask the bot “what does this command do?” by using “!help “. The user can also ask the bot “what commands are there” using the “!list” command. Both these commands fetch details from the plug-in source directly. The documentation here (the ‘user facing’ documentation) is fantastic! It even tells the user about the parameters which the commands need.

The instructions in the bot creation wizard (supybot-create) are just as good, it goes though step by step asking the user questions and giving them useful, relevant information at every step. It offers sensible defaults and issues sensible recommendations to the user. Once the process is complete, the configuration file is again filled with useful documentation about the options in the file.

SupyBot is a fantastic bot, and a useful framework for developing plug-ins. It is technically very advanced and one of the nicer IRC frameworks I’ve looked into. It has a wide user base and a wide range of existing plug-ins. So SupyBot is just bad at documentation? Well, no, not everywhere, but without good documentation it can be very frustrating to work with. The end user facing documentation is fantastic, but the developer facing documentation is poor, or non-existent in places. Writing documentation isn’t always the most interesting or nicest part of software development but it is needed.

* No, SupyBot doesn’t let ops order pizza.