1.. _rest-api: 2 3======================== 4 Mailman 3 Core REST API 5======================== 6 7Here is extensive documentation on the Mailman Core administrative REST API. 8 9 10The REST server 11=============== 12 13Mailman exposes a REST HTTP server for administrative control. 14 15The server listens for connections on a configurable host name and port. 16 17It is always protected by HTTP basic authentication using a single global 18user name and password. The credentials are set in the `[webservice]` section 19of the configuration using the `admin_user` and `admin_pass` properties. 20 21Because the REST server has full administrative access, it should never be 22exposed to the public internet. By default it only listens to connections on 23``localhost``. Don't change this unless you really know what you're doing. 24In addition you should set the user name and password to secure values and 25distribute them to any REST clients with reasonable precautions. 26 27The Mailman major and minor version numbers are in the URL. 28 29You can write your own HTTP clients to speak this API, or you can use the 30`official Python bindings`_. 31 32 33Root URL 34======== 35 36In this documentation, we mainly use ``http://localhost:9001/3.0/`` 37as the REST root url. Port ``9001`` is used for unit tests, but 38for a running system, the port is ``8001`` unless changed in config. 39 40In the documentation we use ``3.0`` as the primary API version, but 41the latest version of the API might be different. You may check the 42difference of versions in `Basic Operation`_. 43 44The ``hostname`` and ``port`` where Mailman's REST API will be 45listening can be found by running `mailman info`_ command. 46You can configure that in ``mailman.cfg`` configuration file.:: 47 48 >>> command = cli('mailman.commands.cli_info.info') 49 50 >>> command('mailman info') 51 GNU Mailman 3... 52 Python ... 53 ... 54 config file: .../test.cfg 55 db url: ... 56 REST root url: http://localhost:9001/3.1/ 57 REST credentials: restadmin:restpass 58 59 60REST API Documentation 61====================== 62 63.. toctree:: 64 :glob: 65 :maxdepth: 1 66 67 ./basic 68 ./collections 69 ./helpers 70 ./systemconf 71 ./domains 72 ./lists 73 ./listconf 74 ./addresses 75 ./users 76 ./membership 77 ./queues 78 ./* 79 80 81.. _`official Python bindings`: https://mailmanclient.readthedocs.io/en/latest/ 82.. _`mailman info`: https://mailman.readthedocs.io/en/latest/src/mailman/config/docs/config.html#which-configuration-file-is-in-use 83.. _`Basic Operation`: https://mailman.readthedocs.io/en/latest/src/mailman/rest/docs/basic.html#api-versions 84