What are the most common mistakes made when designing or implementing APIs?

The most common mistakes I see when try to use an API are typically in the design, but also sometimes in the implementation. An effective API should had have a philosophy that is apparent to the user. This philosophy would be the set of current rules that the API follows, such as only ever returning "interesting" results (I do not appreciate an API that bombards me with "Success" and "OK" status results when I am looking for actual return results or error codes for failures). API methods should look and act similarly in the set. More importantly, the API philosophy should follow a set of rules that the programmer can depend on for updates and API extensions. Too many APIs will immediately deprecate calls vice extending them or adding overloading (in the C++ world) for the method and this breaks and inherent rule of APIs - the user should rarely ever have to make code changes to keep up with new API releases. And the API should be optimized to fail fast as well as be optimized for I/O. These are the most common mistakes that I see across different APIs I have used, and these are the rules that I have followed as an API designer/developer with success.

IMHO this depends on what the API is doing.

If it is a math library to extend a programming language, then the limitations include what the library offers, how you need to interface with it, and can it be used with your language easily or does it require 100 lines of code to get it working? If it can be implemented easily, then that's it, and is a reasonable solution. If the API breaks the programmer can write his own, but the large chunk of his code is his to start with.

If the API however is basically *the* program, and the program works by making a bazillion calls to the API (as it seems a lot of web apps do these days), with a bit of supporting code that relies in large part on the API for success or failure, then I wouldn't call it an API so much as a lazy way to "write" code. It is getting to be not far off drag-and-drop programming. Trouble is, applications will end up being largely the same, and inefficient. If the API breaks or stops working in a particular way, you've had it.

A few notes:

For performance:

An interface should avoid fine grained calls to data sources by prefering object data types over native data types. For example, accept a customer data transfer object as and do not expose methos which set individual properties of a Customer object.

Prefer asynchronous calls to remote systems or constrained local systems

If possible cache static lookup information across method invocations rather than query the lookup service each time.

Avoid global transactions, especially if any of the participants is an asynchronous transaction.

Avoid api call 'side effects': clean-up resources after getting the work done; avoid introducing state into the api call.

For Sanity:
Pay careful attention to the 'units' in the api. If you choose to work in 'milliseconds' always accept and return milliseconds only. If internally you want to work with other units, do convesions in a single private metod, but do not expose this conversion method to users.

Protect the user from making call mistakes. Validate input, but don't obfuscate your code in doing so.

Try to avoid optional parameters when possible, nobody likes to try to remember what's mandatory and what is optional. Emphasize convenience and ease of use. Assume the user will make mistakes. Do not demand that an api user memorize api domain info.

Many more and many very good resources cited by those answering before me. I listed some of the issues I see frequently or that stayed with me from my reading.