Zulip API documentation is currently:
The examples at https://github.com/zulip/zulip/tree/master/api/examples demonstrate much more functionality, which ought to be reflected in the documentation.
A substantive sandbox (like what Swagger provides or like https://en.wikipedia.org/wiki/Special:ApiSandbox) available on an already-running test installation would be great.
Since the api/ directory is distributed as the "API bindings tarball" on http://zulip.com/api , as @timabbott has pointed out, that bundle should probably continue to be be a coherent bundle with relevant documentation inside.
Feel free to break this issue up into multiple tasks, of course.
Also see #671.