[jira] [Updated] (JAMES-3045) Alleviate ambiguity in Alias/Mapping documentation

["Rémi Kowalski (Jira)" <se...@james.apache.org>]

     [ https://issues.apache.org/jira/browse/JAMES-3045?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Rémi Kowalski updated JAMES-3045:
---------------------------------
    Description: 
The correct usage of the Mapping in for defining/retrieving alias in James is by defining them with the source of the Mapping set to the alias and with the destination being the user we want to add an alias to.

As it can be seen inthe documentation [http://james.apache.org/server/manage-webadmin.html#Creating_address_aliases]

we can see that to add an alias we have the following endpoint : 
 curl -XPUT [http://ip:port/address/aliases/user@domain.com/sources/alias@domain.com]

Where the first parameter, the user is the destination of the mapping and the second parameter, the alias address is its source.

However the unit tests for MappingRoutes are confusing in particular getUserMappingsShouldReturnCorrespondingMappingsFromUsername
 because here it is the user which is the source of the mapping and the alias which is the destination.

The documentation [http://james.apache.org/server/manage-webadmin.html#User_mappings] indicate
 that to list all the mappings of a user we should use the following endpoint : 
 curl -XGET [http://ip:port/mappings/user/userAddress]

Where we could expect that userAddress is the address of the user and should be a mapping destination.
 BUT in the code and unit tests, it is a mapping source.

The code is not wrong, but the documentation is misleading, it should be clear that this API indicate the list of the mappings of a "source" which generally is an alias and not a user.

*The actions needed are :*
 * Review and alleviate the ambiguity in the mappings documentation.
 * Change if needed the name of the parameters in the code to clarify the expected usage.
 * And review and update the name of the variable used in the unit tests particularly in `MappingRoutesTest.getUserMappingsShouldReturnCorrespondingMappingsFromUsername`

  was:
The correct usage of the Mapping in for defining/retrieving alias in James is by defining them with the source of the Mapping set to the alias and with the destination being the user we want to add an alias to.

As it can be seen inthe documentation http://james.apache.org/server/manage-webadmin.html#Creating_address_aliases

we can see that to add an alias we have the following endpoint : 
curl -XPUT http://ip:port/address/aliases/user@domain.com/sources/alias@domain.com

Where the first parameter, the user is the destination of the mapping and the second parameter, the alias address is its source.


However the unit tests for MappingRoutes are confusing in particular getUserMappingsShouldReturnCorrespondingMappingsFromUsername
because here it is the user which is the source of the mapping and the alias which is the destination.

The documentation http://james.apache.org/server/manage-webadmin.html#User_mappings indicate
that to list all the mappings of a user we should use the following endpoint : 
curl -XGET http://ip:port/mappings/user/userAddress

Where we could expect that userAddress is the address of the user and should be a mapping destination.
BUT in the code and unit tests, it is a mapping source.

The code is not wrong, but the documentation is misleading, it should be clear that this API indicate the list of the mappings of a "source" which generally is an alias and not a user.


**The actions needed are :**

* Review and alleviate the ambiguity in the mappings documentation.
* Change if needed the name of the parameters in the code to clarify the expected usage.
* And review and update the name of the variable used in the unit tests particularly in `MappingRoutesTest.getUserMappingsShouldReturnCorrespondingMappingsFromUsername`


> Alleviate ambiguity in Alias/Mapping documentation
> --------------------------------------------------
>
>                 Key: JAMES-3045
>                 URL: https://issues.apache.org/jira/browse/JAMES-3045
>             Project: James Server
>          Issue Type: Improvement
>            Reporter: Rémi Kowalski
>            Priority: Major
>
> The correct usage of the Mapping in for defining/retrieving alias in James is by defining them with the source of the Mapping set to the alias and with the destination being the user we want to add an alias to.
> As it can be seen inthe documentation [http://james.apache.org/server/manage-webadmin.html#Creating_address_aliases]
> we can see that to add an alias we have the following endpoint : 
>  curl -XPUT [http://ip:port/address/aliases/user@domain.com/sources/alias@domain.com]
> Where the first parameter, the user is the destination of the mapping and the second parameter, the alias address is its source.
> However the unit tests for MappingRoutes are confusing in particular getUserMappingsShouldReturnCorrespondingMappingsFromUsername
>  because here it is the user which is the source of the mapping and the alias which is the destination.
> The documentation [http://james.apache.org/server/manage-webadmin.html#User_mappings] indicate
>  that to list all the mappings of a user we should use the following endpoint : 
>  curl -XGET [http://ip:port/mappings/user/userAddress]
> Where we could expect that userAddress is the address of the user and should be a mapping destination.
>  BUT in the code and unit tests, it is a mapping source.
> The code is not wrong, but the documentation is misleading, it should be clear that this API indicate the list of the mappings of a "source" which generally is an alias and not a user.
> *The actions needed are :*
>  * Review and alleviate the ambiguity in the mappings documentation.
>  * Change if needed the name of the parameters in the code to clarify the expected usage.
>  * And review and update the name of the variable used in the unit tests particularly in `MappingRoutesTest.getUserMappingsShouldReturnCorrespondingMappingsFromUsername`



--
This message was sent by Atlassian Jira
(v8.3.4#803005)

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org