[Mailman-Developers] REST API first pass at Swagger spec

[Andrew Stuart]

The Swagger spec defines a way to document the methods, properties and return values of a REST API using JSON, and also provides a front end user interface to turn that JSON into a functioning user interface to directly query the API. There seems to be a few choices for documentation REST APIs at the moment (http://apiary.io & http://www.mashery.com/product/io-docs) but Swagger appears to have the industry momentum.

I’ve put together a Swagger spec mainly because I’ve experienced enough pain with REST APIs in the past to know that development goes much, much more smoothly when you have a single place that shows all the available API methods, their parameters and return values, ideally live so you can see it working. Instead of digging through source code and written documentation to find how the REST API works, it’s all right there in front of you.

Once the REST API is documented in JSON, a range of things become possible including writing tests, command lines interfaces, clients and servers that “build themselves” to a greater or lesser extent directly from the JSON REST API spec.

Sorry, that was five long lines :-)

On 11 Jan 2015, at 4:23 pm, Stephen J. Turnbull <stephen at xemacs.org> wrote:

Andrew Stuart writes:

> Attached is a first pass at a Swagger spec for the REST API.
> 
> You can find out about Swagger at http://swagger.io

tmc;wr[1] Please explain briefly what Swagger is and why you're using
it rather than some similar product.  Two lines is enough.  I have
ZERO intention of paying attention to what you're doing; my technical
plate is full, and Barry's the boss anyway.  But if some new person or
a GSoC student seems to have an interest in "that kind of thing" I'd
like to know enough to say "go talk to Andrew".

Footnotes: 
[1]  Too many clicks; won't read.