filling out api to some extent and adding comments