Well said by many above. Would phrase some thoughts as follows: 1. Developer Experience (DX) - How quickly can a developer get up and running trying the API (

Well said by many above. Would phrase some thoughts as follows: 1. Developer Experience (DX) - How quickly can a developer get up and running trying the API (ideally immediately). - Client code generation. - How understandable is the API? Does it use common vocabulary or terms you have to think about what they mean? 2. Accuracy of documentation - API and docs in sync. - Ease of locating items in the documentation. 3. Debugabbility - How easy is it to figure out why requests fail. - How easy is it to test edge cases for success/failure and experiment. 4. Consumer participation in design/prototyping design tools - Mocking functionality. - Collaboration in design that is immediately possible to test. - Making it easy to get feedback on different design options. In the end of the day, good design makes for a good API. And, being able to involve a variety of stakeholders in the design process in a human-friendly way is really important to achieve that goal. As a contributor to ApiBlueprint [1], we have been working to develop a suite of tools to help all this. I include a link to a sample api blueprint [2] and to the public documentation/DX portal you get if you import it and render documentation for it in apiary.io [3]. [1] http://apiblueprint.org/ http://apiblueprint.org/ [2] https://gist.github.com/fosrias/6377469bf0e1d2fd10c7 https://gist.github.com/fosrias/6377469bf0e1d2fd10c7 [3] http://docs.sampleapi42.apiary.io/ http://docs.sampleapi42.apiary.io/