[Mailman-Developers] /3.0/addresses/cris at example.com/user' - multi purpose REST API method

[Andrew Stuart]

TLDR - This API methods does multiple things and depends on information apart from the URL to define its behaviour mode, making it hard to give a clear authentication scope to. I wonder if it should be broken out into individual REST API methods, each with a single purpose and a clear authentication scope.

As background information, from the documentation:

“”"To link an address to a user, a POST request can be sent to the ``/user`` sub-resource of the address.  If the user does not exist, it will be created.””"

    >>> dump_json('http://localhost:9001/3.0/addresses/cris@example.com/user',
    ...           {'display_name': 'Cris X. Person’})


My question is - I am interested to understand the thinking behind this REST method.

It is effectively a multi purpose method.  

In one case it *creates an email address* and *creates a new user* and which are linked to each other.  
In one case it *creates an email address* and links that address to an existing user, when given a POSTed user_id.
In one case it *creates an email address* and does not link it to any user, if the auto_create POST option is False.

In terms of building an authentication system this REST method is problematic. All (I think at this stage anyway) other methods in the REST API can be given a clear authentication scope/role based only on the URL. This REST API method, dual to its multi purpose, mode options-in-the-POST-data behaviour, cannot be given an authentication scope based only on the URL.

Each of the above behaviours have a different authentication scope/role. For example:

(permitted by superuser only) In one case it *creates an email address* and *creates a new user* and which are linked to each other.  

(permitted by superuser only, permitted by existing user) In one case it *creates an email address* and links that address to an existing user, when given a POSTed user_id.

(permitted by superuser only) In one case it *creates an email address* and does not link it to any user, if the auto_create POST option is False.

I’m interested to hear thoughts on this. It would be good if the authentication scope of every REST API URL could be defined based only on the URL, without the need to know either options provided in the form data, or whether or not other records such as user records exist.

In summary - This API methods does too many things and depends on information apart from the URL to define its behaviour, making it hard to give a clear authentication scope to. I wonder if it should be broken out into individual REST API methods, each with a single purpose and a clear authentication scope.