updated documentation and test that show that our API does not currently work to spec.