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

[Barry Warsaw]

On Jan 12, 2015, at 12:47 PM, Andrew Stuart wrote:

>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.

Agreed.

>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.

MM3 does not have a static file server, but I think we could serve the file as
an API endpoint.  Perhaps /<api>/api-docs.json or if that's difficult to
implement, /<api>/system/api-docs.json.

>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 worry a little bit about the extra work to keep it up-to-date when I change
the API, but maybe it won't be so bad in practice.

I wonder if there are any automated testing tools that can be integrated in
the test suite.  I.e. something that grabs the api-docs.json and then makes
calls against the API to verify endpoints, arguments, and return values.  Do
you know of any such tool?

>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.

Sounds good!

Cheers,
-Barry