What exactly do you have in mind, as a lot of the rest-api
should be annotated wit Swagger annotations and the
documentation at http://www.hawkular.org/docs/rest/
is generated via Swagger -> markup

> Im particularly interested in looking into how a user can subscribe to, and
> receive specific alerts using push. Does the android app use Aerogear?

Yes it does. And I think Thomas Segismont has done some work
in that area already. It would be for sure nice to be able to better
integrate all that.