Filling in specs for the API, mostly

Signed-off-by: Nicola Adamchik <n.adamchik@modcloth.com>