An explicit API is usually quite self-explanatory, the method name tells you what the method does (at least, if it has a good name). Some examples from the core of CakePHP:

Model::findAll($conditions = null, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null)  // deprecated
Model::findCount($conditions = null, $recursive = 0)  // deprecated
FormHelper::checkbox($fieldName, $options = array())
FormHelper::submit($caption = null, $options = array())

On the other hand, an implicit API doesn’t tell you what the method does (respectively it does it on a more abstract level):

Model::find($type, $options = array())  // new syntax
FormHelper::input($fieldName, $options = array())

In the first example, the $type parameter determines what the method does, and in the second example it depends either on the data type of the respective database field or on the value of the “type” option.

For you as a developer, implementing an implicit API means a) you have to write more code and b) you have to write more documentation (because you also have to explain what the method does)… On the other hand, an implicit API allows you to provide a unified API (e.g. Model::find(‘all’), Model::find(‘count’), and Model::find(‘list’) vs. Model::findAll(), Model::findCount(), and Model::generateList()).

For a user, an implicit API is probably more difficult to use than an explicit API, at least in the beginning. For example, if you want to get the number of some records, you first look for a method with “count” in its name. With an explicit API you will find the Model::findCount() method, but with an implicit API you probably won’t discover that Model::find() supports a “count” type…

Anyway, in the end it is up to you to decide which approach better fits to your specific situation. Both approaches have their advantages and disadvantages.

I have one of those lists you will find in almost every application which lists the items the user entered. Now it should be possible to move these items to two different categories. How could this be solved?

The easiest solution would be to add two links to the end of each row. But how do you name those links? “Move to Category A” and “Move to Category B”? Hm, that takes too much space and it looks ugly if you have to repeat it on all rows.

The next idea is to use icons instead of text. But this causes a similar problem as above. How should the icons look so people understand them?

Another idea is to put a checkbox in front of each row and to have a select box with the possible actions at the top and/or the bottom of the list. The problem here is that the user has to click at least three times to move an item.

What about a drag and drop solution? Well, drag and drop is not very intuitive, and it is difficult to visualize that an object is draggable.

Maybe we could add a select box to the end of each row? Well, it is still two clicks for the user. Can we reduce it somehow to a one-click action?

We could add a link to the end of each row and then on a mouse over event we show the possible actions. So with only one click the user can move a list item to the desired category. With that I have found the solution for the problem described at the beginning of this post. Here the visualization of this idea which I called “expandable link”:

The first image shows simply a link, and the second shows what happens on a mouse over event on this link.

Up to now I didn’t test this solution in the wild so I cannot say how it will be accepted by the users, but if they are like me, they will find it cool ;-)