[Mailman-Developers] MM 3 REST API

[Andrew Stuart]

Hi Tom,

This is a Swagger spedification for the MM3 REST API - it defines the entire API. Note that this specification is about six months old so changes in the past six months would not be there. The specification document is here:
https://gitlab.com/astuart/mailmania/blob/master/serve_spec_mailman_rest_api/api-docs.json

You can interactively navigate above the MM3 REST API Swagger specification here:
http://supercoders.com.au/swagger-ui/dist/index.html
(Barry if you want to put this somewhere else you just unzip this http://supercoders.com.au/mm3swagger.zip onto a web server and you’re good to go)


You can also programmatically drive the MM3 REST API using the above spec - it is just JSON so you read in the URL field and construct your URL and send it. Mailmania uses it for constructing requests to the MM3 REST API and for constructing tests for the MM3 REST API.

The above links and zipfile use an old version of the Swagger editor - if you want the latest version of the Swagger editor, download it here:
https://github.com/swagger-api/swagger-ui

Important:
The Swagger specification correctly defines the available URLs and correctly defines the HTTP methods available for accessing them.
https://gitlab.com/astuart/mailmania/blob/master/serve_spec_mailman_rest_api/api-docs.json
The Swagger specification correctly defines MM3 REST API structure of the available URLs
The Swagger specification correctly defines MM3 REST API HTTP methods available 
The Swagger specification correctly defines MM3 REST API input field names
The Swagger specification correctly defines MM3 REST API input field parameter types (i.e. URL or form data)

The Swagger specification does not correctly define response fields- any response fields present in the spec document are probably not correct.
The Swagger specification does not correctly define response status codes - any response fields present in the spec document are probably not correct.
The Swagger specification does not correctly define response error codes returned - any error codes present in the spec document are probably not correct.


In summary, the spec should be correct for input but it is not correct for output/responses.  There is probably a good project for a GSOC student to verify and update the spec and define the API response fields/codes and ensure it works with the latest Swagger editor.

>>I'd welcome contributions to help make the REST API more discoverable and/or better documented.
The Falcon MM3 REST API could return this as a static file to make the API discoverable: https://gitlab.com/astuart/mailmania/blob/master/serve_spec_mailman_rest_api/api-docs.json

Any questions I’m happy to answer.

Andrew Stuart