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

[Andrew Stuart]

With Swagger you can either:
1: integrate the spec into the API source code
 or 
2: have one single standalone JSON file that contains the whole specification (api-docs.json in this case)

I’m not a fan of integrating the Swagger specification into the code - seems to make for a VERY large amount of work, a huge amount of complexity and massive potential for introduction of bugs.

I’ve taken the approach of a single static JSON file - MUCH more simple.  All Mailman would need is to include this file (api-docs.json)  as a static file that can be read or if there is no static file server in Mailman (is there? I haven’t looked) maybe create an api-docs.json endpoint in the API that returns the static file. Any tools that want to use the api-docs.json spec file don’t need to be included in Mailman core.

The api-docs.json spec file would need to be kept up to date when the Mailman API changes but it’s really straightforward - building it in the first place is just tedious research on the methods and properties but maintaining it should be a matter of a few minutes work to update it when the API changes.

I’ll need to finish it up.  I’m not sure what to do about getting a pair of eyes to QA verify it, but maybe we can cross that bridge after I’ve finished it.


On 12 Jan 2015, at 12:19 pm, Barry Warsaw <barry at list.org> wrote:

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.

Cheers,
-Barry
_______________________________________________
Mailman-Developers mailing list
Mailman-Developers at python.org
https://mail.python.org/mailman/listinfo/mailman-developers
Mailman FAQ: http://wiki.list.org/x/AgA3
Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/
Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40supercoders.com.au

Security Policy: http://wiki.list.org/x/QIA9