====== Generic Rest API for Mailing List Managers ======

===== v0.2 (as of 2016-02-18) =====

currently supported:
  * mailman

planned: 
  * sympa

maybe: 
  * ezmlm
  * majordomo 
  * /etc/aliases :include:
  * ?

==== Functionality =====

  * subscribe
  * unsubscribe
  * enquiry of an address
  * member count 
  * member checksum: sha265, hex digest

==== Interface ====

  * <nowiki>https://<web.frontend.server>/mlm-api/<mailing.list.server>/<listname>/<mailaddr></nowiki>
    * GET - enquire mail address
    * POST - add mail address
    * DELETE - remove mail address
  * <nowiki>https://<web.frontend.server>/mlm-api/<mailing.list.server>/<listname>/*/count</nowiki>
  * <nowiki>https://<web.frontend.server>/mlm-api/<mailing.list.server>/<listname>/*/sha256</nowiki>

=== checksum calculation ===

  * pseudocode: list members | lowercase | sort | sha256 (hex)
  * sh: list_members mitglieder | tr 'A-Z' 'a-z' | sort | tr -d '\n' | sha256sum

==== Examples ====
  
<code>
# check:
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/john.doe@example.org 
  -> ''
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/*/count
  -> 23
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/*/sha256
  -> d95802911a5eff4b3d757f1a20bd021c51c7d1ea418f76162cedb48a6016aa4d

# add member:
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/john.doe@example.org -X POST -d ''
  -> ''

# check again:
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/john.doe@example.org
  -> 'john.doe@example.org'
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/*/count
  -> 24
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/*/sha256
  -> 3ef60a43d296065c6e4bd0a41c9fee5c140eaa9ed91071a4c98d2347e412f227

# remove member:
curl https://www.example.org/mlm-api/lists.example.org/staff/john.doe@example.org -X DELETE
  -> ''

# check once more:
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/*/count
  -> 23
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/john.doe@example.org
  -> ''
curl -u adminuser https://www.example.org/mlm-api/lists.example.org/staff/*/sha256
  -> d95802911a5eff4b3d757f1a20bd021c51c7d1ea418f76162cedb48a6016aa4d
</code>

==== Installation ====

Example from Debian 7/8 Apache installation with Mailman:

<code>

# mlm-api is stored as /var/www/{my.domain}/exec/mlm-api

touch /etc/sudoers.d/mlm-api
visudo -f /etc/sudoers.d/mlm-api
        www-data ALL=(list:ALL) NOPASSWD: /usr/sbin/list_members
        www-data ALL=(list:ALL) NOPASSWD: /usr/sbin/add_members
        www-data ALL=(list:ALL) NOPASSWD: /usr/sbin/remove_members

touch    /var/www/{my.domain}/auth/htpasswd-mlm-api
htpasswd /var/www/{my.domain}/auth/htpasswd-mlm-api {user1}
htpasswd /var/www/{my.domain}/auth/htpasswd-mlm-api {user2}

/etc/apache/sites-available/{my.domain}.conf

    ScriptAlias /mlm-api    /var/www/{my.domain}/exec/mlm-api

    <location /mlm-api >
            AuthType Basic
            AuthName mlm-api
            AuthUserFile /var/www/{my.domain}/auth/htpasswd-mlm-api
            require valid-user
    </location>

/etc/init.d/apache2 reload

</code>