Making APIs Usable

Like any other product, service, or technology, an API needs to be usable, to succeed.

Here are some of the things that typical APIs can do to improve usability:

1. Readable names. The name should describe what the routine does.
2. Consistent names. If one routine is getX, a similar routine should be getY, rather than returnY or getYvalue.
3. Common arguments first. The extreme is the “invariant”, where every API in a group requires a reference to the same thing. Such arguments should always be first in the argument-list. So if a .addTo(target) operation that adds the value of the current object to a target object, then a function that adds a constant should be .add(target, constant), rather than .add(constant, target). because, while a single instance is not hard to remember, it becomes impossible to remember them all when you have hundreds.
4. Same arguments have same type. If a value is passed as a string in one API, it should not necessary to parse it to extract the value to pass it to a different API. Either the onus for parsing is on the calling routine (for maximum speed), or on the called routine (for maximum ease of use). But it is never the case that it is passed in two different ways. (For the epitome of both speed and ease of use, offer a routine that does the parsing and extracts the value, and then require that value for each of the APIs.)
5. Arguments and return values dovetail. The value returned by one routine should be in the same form that will be required in common API sequence. So if one routine opens a file, and other writes to it, the routine that opens the file should return the value that is directly consumed by the writing routine, without intermediate processing.

Finally, note that Technical Writers Make Great Usability Testers & and Designers. They should be involved in the review process as early as possible, precisely because they are so adept at noticing inconsistencies and potential areas for improvement.

Copyright © 2017, TreeLight PenWorks

Please share!