We have some REST API docs that need improving and updating:
* Improve clarity of the current documentation
* bring the documentation inline with the actual API (there are some places where the API doesn't behave exactly as documented)
* extend the documentation to ensure it's complete - there are currently some return fields, etc, that are not documented at all
Whilst this is a one-time project, we have a number of other APIs that are either being written or need review.