Adds doc strings to API FunctionalTest class

The API FunctionalTest class in ironic/tests/api/base.py lacks doc
strings, and some of the methods' functionality may not be obvious
to everyone. This adds doc strings that, for the most part, are
copied from ceilometer/tests/api/__init__.py. (base.py was ported
from that ceilometer file.)

The code from post_json() was moved to _request_json(), to make
post_json() more consistent with the corresponding patch/put methods.

This also undoes https://review.openstack.org/#/c/38909/ because
it was decided that the original version was more readable.

Change-Id: I92dad5bb77f4834604e61c28303ee8b0acc60ea1
Closes-Bug: #1193666
Merge "Adds doc strings to API FunctionalTest class"