Tao of Good API Design
Focus on what matters.
Data is your API. Understanding data and what consumers can do with it is the key to a successful API design, implementation and use.
Yet, over and over we see API documentation focused on technical details. We hear confused stakeholders, missed expectations, and frustrated developers. We rely on untested code, hard-coded understanding that can't be evolved and input that wasn't validated.
All of this can be fixed by focusing on what matters the most—data and affordances.
The first step is to get everyone on the same page about what data is in the system and what they mean. No understanding of data is complete without the description of its affordances. Understanding what consumer can do with data is equally as important as understanding the meaning of data.
Finally, to get much-needed interoperability and automation, both the description of data and its affordances should be readable to machines.(why?)