We've created an task in JIRA to enhance the RESTful API: MODE-1583. If you have any thoughts on how we can improve the RESTful API (including things that might not be backward compatible), please comment on the JIRA or post on this thread. (See also the related issues MODE-1584 and MODE-1541, too.)
You can get a quick overview of what the current service "looks like" here: https://docs.jboss.org/author/display/MODE28/Accessing+ModeShape+Remotely#AccessingModeShapeRemotely-TheModeShapeRESTServer