filling out api properly from rest docs
more rest api following