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

[Abhilash Raj]

Hi Scott,

On Mon, 2017-11-20 at 11:20 -0600, Scott Koranda wrote:
> 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/addr
> esses
> 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.6FJpMFM
> UTDdDXULAmwdN8YW92w87EdctgqFqAUkUqS6.EOTCz/",
>     "preferred_address": "skoranda at example.nil",
>     "self_link": "http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac958b1
> 8882a6d8",
>     "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/addr
> esses | 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@exa
> mple.nil",
>             "user": "http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac95
> 8b18882a6d8",
>             "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@e
> xample.nil",
>             "user": "http://mytestbed.com:8001/3.1/users/e57ecfd0c0c74a319ac95
> 8b18882a6d8",
>             "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 think these all seem like reasonable additions. 

- an extra `preferred` boolean attribute when creating an address is good, I
couldn't find an endpoint to actually change the preferred_address of a user, so
this is good.

- I think instead of embedding the `preferred_address` in user (/user/<uid>), we
 could have a sub-resource that represents the preferred address, if any exists.
so something like /user/<uid</preferred_address

- The rest of the operations about the preferred address would then be based on
GET/POST on this sub-resource. I don't think there is a need to do PATCH for
this sub-resource.

I hope that it was helpful!

How does that sound?

> 
> I will also begin the "copyright assignment" paperwork as explained at
> 
> https://wiki.list.org/DEV/Home

Great!

> 
> Thank you for your consideration.

Thank you for taking time to contribute to Mailman! :)

-- 
thanks,
Abhilash Raj