Disclaimer: I work for Apiary.

API Blueprint [1] is an open source API description format which can be used to intuitively describe an API.

MSON [2] is a recent addition to the above format which makes it easy to describe all kinds of complex requests and responses in the spec.

You can email me at pavan [at] apiary [dot] io if you have any more questions.

[1]: http://apiblueprint.org

[2]: http://github.com/apiaryio/mson