examples for user-facing API discussion