[Mailman-Developers] 3.1.x REST API enhancements around preferred email address
Scott Koranda
skoranda at gmail.com
Thu Mar 8 11:34:50 EST 2018
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 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.
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 at gnu.org and cc'd
mailman-cabal at 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
More information about the Mailman-Developers
mailing list