created the preliminary api file

This is a major work in progress. A lot of things need to be changed and
clarified before this is finalized as the api.