Hello,

My apologies for a late reply. The work to slightly extend the REST API has once again come to the top of my queue.

Please see inline comments and a question below.

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@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@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@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@example.nil", "http_etag": "\"492824d150f9f11e32d530d3cad0f76422bddb48\"", "original_email": "skoranda01@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@example.nil", "http_etag": "\"f0f28c1c6a925a595269d3fe21ef7fc1515d7670\"", "original_email": "skoranda01@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.

Thank you for looking at it in detail.

• 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

I understand and I will proceed in this direction.

• 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!

It was, thank you.

How does that sound?

Good. I would like to proceed in a way that makes it as easy as possible for you to consider the changes.

...

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

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

Great!

I have sent the first email/form to fsf-records@gnu.org and cc'd mailman-cabal@python.org.

I will email again after I have sent the second form.

My primary question is which branch at

https://gitlab.com/mailman/mailman.git

should I work from and then target a merge request at? I presume it would be the release-3.1 branch. Is that correct, or should it be against master?

Thank you,

Scott K