[Mailman-Developers] 3.1.x REST API enhancements around preferred email address

[Scott Koranda]

Hello,

I am interested in contributing enhancements around preferred address 
to the REST API for version 3.1.x. 

To prove out my use case(s) and familiarize myself with the code I have 
made changes already. Here are some example curl command line
invocations and output to illustrate:

1) Create an address for an existing user and mark that address as the
user's preferred address:

curl -u restadmin:restpass \
     -X POST \
     -d email=skoranda at example.nil \
     -d preferred=1 \
     http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8/addresses

This returns a '201 Created'.

2) Return the preferred address, if set, for a user:

curl -u restadmin:restpass \
     -X GET \
    http://mystestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8 | python -m json.tool

{
    "created_on": "2017-11-11T22:20:45.950949",
    "display_name": "Scott Koranda",
    "http_etag": "\"26bc0d9f21eb145248884aedae4c1ffd00b608d2\"",
    "is_server_owner": false,
    "password": "$6$rounds=656000$gWGfwpajfZ7rVn5O$Sl559B2TgtpJWXA2i67G5ukjzkV6iTp4NgP.6FJpMFMUTDdDXULAmwdN8YW92w87EdctgqFqAUkUqS6.EOTCz/",
    "preferred_address": "skoranda at example.nil",
    "self_link": "http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8",
    "user_id": "e57ecfd0c0c74a319ac958b18882a6d8"
}

3) Update/patch a user to set a preferred address:

curl -u restadmin:restpass \
     -X PATCH \
     -d preferred_address=skoranda at example.nil \
    http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8 

This returns a '204 No Content'.

4) Get all addresses for a user with the preferred address (if set) having
the attribute 'preferred' set to 'true':

curl -u restadmin:restpass \
     -X GET \
     http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8/addresses | python -m json.tool

{
    "entries": [
        {
            "email": "skoranda at example.nil",
            "http_etag": "\"492824d150f9f11e32d530d3cad0f76422bddb48\"",
            "original_email": "skoranda01 at example.nil",
            "preferred": true,
            "registered_on": "2017-11-13T22:35:17.232180",
            "self_link": "http://mytestbed.com:8001/3.1/addresses/skoranda@example.nil",
            "user": "http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8",
            "verified_on": "2017-11-20T16:48:51.738145"
        },
        {
            "email": "skoranda01 at example.nil",
            "http_etag": "\"f0f28c1c6a925a595269d3fe21ef7fc1515d7670\"",
            "original_email": "skoranda01 at example.nil",
            "registered_on": "2017-11-20T16:46:20.941262",
            "self_link": "http://mytestbed.com:8001/3.1/addresses/skoranda01@example.nil",
            "user": "http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b18882a6d8",
            "verified_on": "2017-11-20T16:46:20.941595"
        },
    ],
    "http_etag": "\"89c46bd312c6f1a344e6e6180aed6f11b62e6048\"",
    "start": 0,
    "total_size": 2
}

Before I submit a pull request I would be grateful for any comments
or feedback on the functionality as illustrated above, or any other comments
or feedback.

I will also begin the "copyright assignment" paperwork as explained at

https://wiki.list.org/DEV/Home

Thank you for your consideration.

Sincerely,

Scott Koranda