Provide written spec

[Faerbit]

For someone new to this it is very hard to get how the API should behave by only looking at the tests.
I found it difficult to deduce what should happen if you issue a DELETE request to the API root.
I am still unsure how the order property should be handled. Is it completely optional?

Failed tests also do not give helpful information if you do not know how the API should behave.

[moredip]

Thanks for the feedback. It's very helpful to hear from implementers so we can hopefully lower the cost for future implementations.

@Faerbit would you be interested in taking a stab at writing a draft of a spec? Perhaps using something like Swagger?

[Faerbit]

I'll give it a try in the following days.

[Faerbit]

I did not really get along with Swagger. The error reporting is kind of bad. So I produced something in Markdown:
https://gist.github.com/Faerbit/baba66c27f95cd0f12ce

[moredip]

This looks good. If you want to add the doc to the site feel free to send a PR. Or I can add it if you'd prefer.

[Faerbit]

I wouldn't really know where to add it. I would prefer if you would do it.

[darrenhaken]

Any update on whether this got merged? I agree btw that new docs would have been handy for certain things