add REST documentation for principals module

@sathomas : Are the PRs ready for review or did you want to merge some of them together? They are currently still labelled as `More work needed`.