Toolserver:Tool considerations

There are a number of considerations that should be made when determining whether to or how to make a Toolserver tool. This page lists some of the most important considerations.

Necessity
The first thing that needs to be considered is whether a similar tool already exists. There is no authoritative directory of Toolserver tools, though there is Interiot's tstoc. While writing your own tool can be a good learning experience, it isn't always the best use of resources, especially developer time.

Another consideration to make, especially if you're coding in PHP, is whether your tool or script is better suited as a MediaWiki extension.

Multi-maintainer tools
Multi-maintainer projects are available to Toolserver tools. Setting up a multi-maintainer tool has a number of benefits, but to end users the biggest benefit is a stable URL.

Abstraction
Code abstraction is one of the more important considerations when designing a Toolserver tool.

As an example, it's trivial to create a script that takes the contents of the speedy deletion category on a certain wiki and arranges the content by size. However, this tool won't work for any project that doesn't use the category name "Candidates for speedy deletion". Even if you programmed the tool with every translation and iteration of the speedy deletion categories, it wouldn't support other categories that users might want to query.

A much better solution is to create a tool that allows the user to select a specific wiki database and select a specific category. The flexibility to this approach reduces tool duplication and provides a better service for the end users.

When possible, tools should be designed to support every active wiki database, though it's fine to set a default database if a database is unspecified (this is especially important for historical URLs).

Never hard-code namespace names or site URLs. These should always be queried from the Toolserver database.

Security
Sanitize user input. Always! This is especially important if a tool is running SQL queries based on user input. Be sure that the input is sanitized so that it doesn't the script to unexpectedly error or allow end-users to run code that they should not be able to run.

Sanitize output. Your tools should escape special characters in HTML to avoid cross-site scripting vulnerabilities. In particular, the "&lt;" and "&gt;" characters must be escaped. Also, quote characters should must be escaped, for example  is dangerous if   is passed to it. You may have to escape single quotes as well if your use them in your HTML. Most modern programming languages contain pre-built functions to escape these dangerous characters for you. Escaping "&amp;" is less crucial, though it's nice when tools output valid HTML.

Ensure that you don't crash any browsers by outputting too many results.

Place reasonable limits on your code if it involves resource-intensive processes. If a user sets the limit to 500000, it shouldn't cause any problems for the Toolserver servers or the user. Expect and account for user stupidity.

Passwords if collected (we recommend avoiding them) should be hashed (so eve is required to a brute force attach) with a salt (so she can't reuse previous results). Also without a SSL option the toolserver passwords will need to be sent in the clear unless you hash it with javascript.

Internationalization
When designing your tools, remember that not every user will speak the language that your interface is in. Using icons and colors in place of or next to key elements in your interface will allow non-native speakers to understand how to use your tool.

Services like translatewiki.net can be employed to translate your tools, though I don't know much about how that works.