more changes after feedback including a decision table for APIs in intro