How to design a good API

The below is the summary of :

How to Design a Good API & Why it Matters

1 Characteristics of a Good API
-Easy to learn
-Easy to use, even without documentation
-Hard to misuse
-Easy to read and maintain code that uses it
-Sufficiently powerful to satisfy requirements
-Easy to extend

2 General principles

--API should do one thing and do it well  
       --Functionality should be easy to explain
       --If it's hard to name, that's generally a bad sign
       --Good names driver development

--API should be as small as possible but no smaller  
      --API should statsfy its requirements and be powerful.
      --When in doubt leave it out 
      --You can always add, but you can never remove
      --Constraints is acceptable. You won't be able to please everyone

 --Implementation should not impact API
      --Do not overspecify the behavior of methods.   
      --Free to change implemention at anytime
      --Dont't let implemention details "leak" into API

--API Must coexist peacefully with platform
      --Do what is customary
      --Take advantage of API-friendly features
      --Know and avoid API traps and pitfalls
      --Don't transliterate APIs

--Avoid Long Parameter Lists
       --Three or fewer parmater is ideal
       --Long lists of identically typed params harmful 

--Consider Performance Consequences of API Design Desicion.
       --be cautious of the mutability. Eg: resource needs to be allocated each time.

--Documentation Matters    
       --Document for functionality,  each parameters , expection and exception.