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

Barry Warsaw barry at list.org
Mon Jan 12 02:19:18 CET 2015

On Jan 11, 2015, at 08:51 AM, Andrew Stuart wrote:

>Attached is a first pass at a Swagger spec for the REST API.
>You can find out about Swagger at http://swagger.io
>The Swagger spec that I am working on is attached to this message or can be
>found here: http://www.mailripper.com/api-docs.json
>If you want to see the attached spec in action against the Mailman REST API,
>go to http://www.mailripper.com/swagger-ui/index.html
>Give it a try at http://www.mailripper.com/swagger-ui/index.html - you are
>welcome to change anything, it’s a test Mailman server and you can add or
>delete anything - nothing you do will be a problem.
>There’s still a fair bit to do to finalise this but most of the API queries
>are working - enough for you to see how it works.

It looks interesting.  I have a little experience with WADL with the Launchpad
API.  There was a lot of infrastructure built into lazr.restful to
automatically generate the WADL, but it was so cumbersome that I was ecstatic
to remove it all for restish (at the time).

My big question is how to make sure that the swagger spec doesn't get out of
date to the implementation.  I definitely don't want to add a lot of cruft to
the implementation - the light weight of the current falcon-based
implementation is a huge benefit.  It would be okay (maybe ideal) if some how
the swagger spec was integrated with the core's test suite, so that at least
we'd see failures if the API were modified (e.g. new resources and methods
added) without the spec being similarly updated.

Ultimately I think if it isn't much effort to keep up to date, and is useful
to consumers of the API, it could be a good thing, but I don't really have any
opinions about swagger as compared to alternatives.


More information about the Mailman-Developers mailing list