finished API with accompanying test suite