Rest doc improvements

Please, merge the latest rest api docs in master.