1. Documentation. It has been said in other comments. If you do nothing else right, do documentation. It is paramount. Documentation must contain code samples that can be ran without scaffolding a huge project. cURL command lines -- or the equivalent in non-HTTP APIs, are, for me, as good as it gets.
2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable.
3. Resource oriented. Expose your resources, then verbs on top of that. These are application-level resources. Do not directly expose the data model. RESTful APIs obviously follow this, but going REST is not the only option.
4. Stateless, or with as little state as possible. Stateless APIs make clients a lot simpler. They have the added bonus of scaling better on your end (on the server end).
5. Predictable. This is achieved by being both consistent and verbose. Do not use abbreviations on method names. Define a vocabulary and use always the same nouns to refer to the same entities. If using positional arguments, use the same calling order (i.e. avoid the needle/haystack you see in PHP).
2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable.
3. Resource oriented. Expose your resources, then verbs on top of that. These are application-level resources. Do not directly expose the data model. RESTful APIs obviously follow this, but going REST is not the only option.
4. Stateless, or with as little state as possible. Stateless APIs make clients a lot simpler. They have the added bonus of scaling better on your end (on the server end).
5. Predictable. This is achieved by being both consistent and verbose. Do not use abbreviations on method names. Define a vocabulary and use always the same nouns to refer to the same entities. If using positional arguments, use the same calling order (i.e. avoid the needle/haystack you see in PHP).