major updates to API proposal