expanded the API to cover common use cases