API design (choosing which information to expose and the format it takes) is a well-trodden topic with lots of great resources available for reference.
API documentation needs to be simultaneously technically complete and explicit while being human-readable and meaningful. It should take into account realistic design requirements as well as providing things like example usage and sample code.
Questions with this tag should be about either designing an API itself or about documenting it effectively.
Additional resources:
- API Design by Matt Gemmell
- How To Design A Good API And Why It Matters by Joshua Bloch (Google Tech Talk; YouTube link)
- API design for humans by Noah Lorang (37signals)
- Applying Design Principles to API Initiatives by Kevin Swiber and Alan Languirand (presentation; SlideShare link)
- Designing Great API Docs by James Yu
- Creating Great API Documentation: Tools and Techniques by pix0r (Stack Overflow question)
