Re: [Mailman-Developers] MM 3 REST API

On Dec 24, 2015, at 11:08 AM, Tom Browder wrote:
Where should I look for the complete, definitive documentation on the MM3 REST API?
Sadly, there's no programmatic way to gather the specifications for the REST API. The best you have is the online documentation...
http://mailman.readthedocs.org/en/latest/README.html
...and the source. You can refer to two other projects which access the API though, and which might also help.
https://gitlab.com/mailman/mailmanclient - is the official Python bindings to the REST API.
https://gitlab.com/astuart/mailmania - is Andrew Stuart's authenticating proxy, which exposes a public REST API bridging to the internal REST API that the core exposes. At some point, we'll pull this in as an official subproject.
I'd welcome contributions to help make the REST API more discoverable and/or better documented.
Cheers, -Barry

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...
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... 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...
Any questions I’m happy to answer.
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...
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... 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...
Any questions I’m happy to answer.
Andrew Stuart
participants (3)
-
Andrew Stuart
-
Barry Warsaw
-
Tom Browder