updated ./api/* documentation

After documenting the api calls, i might in the future change some of
the longer function calls to have just have a single obj which has all
the params (especially in oscar_api.js)