revised and documented the first bit of the API