How to design an API for different users and levels of control?

Question

I am developing a key value store abstraction layer, much like JDBC or ActiveRecord, and I would like to provide varying levels of API, such that at its most basic it is:

get Key
set Key, Value
exists Key
delete Key

However, I also want to provide another API which provides lower level details which can be used with CAP theorem datastores such as:

get Key, Number_of_nodes_to_read_from
set Key, Value, Number_of_nodes_to_write_to
exists Key, Number_of_nodes_to_check
delete Key, Number_of_nodes_to_check, timeout_in_milliseconds

: And to make things really complicated I would also like an API where value added things can be added such as map reducers, indexes, records with fields, searching.

Anyway, my question is whether I should make one huge list of functions, or should I split up the API, bearing in mind that I may wish to add to the API in the future.

Thanks

Zubair

Note: The original question I had is here:

http://stackoverflow.com/questions/2321650/is-this-api-too-simple

Answer 1

In lieu of a long-winded answer, I strongly recommend that you watch the Google Techtalk entitled "How To Design A Good API and Why it Matters", since I believe it addresses your question.

My own recommendation would be to expose your API only through the builtin map or dictionary interface provided by the language, until such time as it becomes necessary to provide users with a higher level of control. If you expose too much from the outset, you will lock yourself into your particular implementation, which is completely contrary to the purpose of an API ... that is, to provide abstraction.

Answer 2

How about get Key, Map_of_params
The second param could be a simple Map of key-values.