factoring out duplication in preparation to port over existing API methods