The purpose of an API is like a company mission statement: There's one version written on the wall and then there's the actual version everybody knows is true but they don't say it out loud.
You described the written one above. GP described the actual one.
