Update Rest API documentation to clarify about /rest/api/2/user/properties/{propertyKey}

Problem Definition

Currently JIRA has a new REST API call for user properties. However, the documentation is not clear on the specifics of this call as explained by the dev in the below 2 comments to linked issues:

1. JRACLOUD-45502:

   The user properties that can be set via the user profile page and the user properties exposed in the JIRA REST API are actually two completely different storage mechanisms, which explains why user properties set from EditUserProperties.jspa are not returned when you call the REST API.

   The new user properties in the REST API are intended to be used by remote integrations and add-ons to store per-user data and settings. This helps add-ons provide a customized experience for each JIRA user while keeping all the data in the JIRA Cloud instance's database. These properties are generally intended to be used by add-ons. We do not plan to build a UI to create and set properties – you are more than welcome to use them, but to retrieve user properties using a GET request on /rest/api/2/user/properties, they must be set with a PUT to /rest/api/2/user/properties/{propertyKey}.

   We absolutely recognize the confusion that having two different sets of user properties can cause, and we intend to rectify this in the future.

2. JRACLOUD-59760:

   There is a free add-on for JIRA Cloud that provides the ability to edit user entity properties, which are accessible via the user entity properties REST API discussed on this issue. 

   We know that one of the most common use cases for user properties is workflow automation. For that reason, add-ons like the new JIRA Misc Workflow Extensions add-on for JIRA Cloud have also implemented their own user interfaces for setting and managing user properties.

   The reason we are not planning to expose a REST API for the legacy user preferences/properties that are currently not accessible via REST is that we are making a number of changes to how users are stored in Atlassian Cloud as we roll out Atlassian accounts. Unfortunately, migrating legacy user preferences to the new user entity properties available via REST is not straightforward.

    

Therefore, users would be attempting to access properties of users created via UI using REST API and also will expect to access properties created via REST API from the UI. However, this is an intended behavior as explained in the above tickets.

Suggested Solution

Please update the doc to clarify the rest call as explained by the dev