Updated api.md to reflect current thinking for the API