some notes on the api