commented proposed api