extend responses api doc

Closes #10

LGTM given by: @marten

Squashed commit of the following:

commit f6e60fe01749ba41eb195f21a6755d84ed985f94
Author: Samuel Esposito <s.esposito@roqua.nl>
Date:   Mon Sep 29 11:13:32 2014 +0200

    tweak wording

commit caccd25497e79a47eff7fccd6b0445e31218dc58
Author: Samuel Esposito <s.esposito@roqua.nl>
Date:   Mon Sep 29 10:52:02 2014 +0200

    extend responses api doc