[docs] more ideas on how the API might look like