Revised description of API

More full account of how the API works.