Awesome Graphs shows statistics based on the emails contributors used when committing changes to the repository. Sometimes one contributor can use different e-mails which can lead to inconsistent and incomplete data shown by Awesome Graphs.

To address this problem, you can manage emails via REST API.

Below on the page, you'll find the details about this option. For easier navigation, use the Table of Contents at the top-right of the page.

You can also use .mailmap in the repository or use aliases in the user profile settings. To learn more about it, please refer to Managing Emails.

Overview 

Via this REST API, it is possible to view, add, delete email aliases of Bitbucket Server / Data Center users. Regular users can perform these operations with their own aliases while Bitbucket system administrators can manage aliases of other users as well.

The REST API for managing user aliases is located at <bitbucket-host>/rest/awesome-graphs/latest/emails

Viewing aliases

Here is the curl command for viewing your own user aliases:

curl -u username:password http://bitbucket-host/rest/awesome-graphs/latest/emails
CODE

For administrators, to view user aliases of others, the curl command needs to include an additional parameter 'user', which value is the username of the user whose alias an administrator wants to view:

curl -u username:password -G -d user=john http://bitbucket-host/rest/awesome-graphs/latest/emails
CODE

Below is an example of  the response:

{
  "start": 0,
  "limit": 25,
  "size": 2,
  "isLastPage": true,
  "values": [
    {"email": "john.smith@gmail.com", "automatically": false},  
    {"email": "John.Smith@gmail.com", "automatically": true}
  ]
}
CODE

An alias has 2 fields: 

  • email - user email address
  • automatically:
    • 'false' means that alias is added manually by a user or via REST API; 
    • 'true' means that alias was automatically linked by Awesome Graphs, which happens when a new email alias is being added and the add-on detects that such an email already exists in the database, but differs in case (e.g., John.Smith@gmail.com and john.smith@gmail.com), and adds this detected email as an automatically linked alias.

Adding aliases

The curl command for adding a new alias needs to include an additional parameter 'email', which value is the email address that should be added as an alias.

Here is the curl command for a user to add a new alias for him/herself.

curl -u username:password -X PUT -G -d email=jsmith@example.com http://bitbucket-host/rest/awesome-graphs/latest/emails
CODE

For administrators, to add a user alias for another user, the curl command is supposed to include an additional parameter 'user', which value is the username of the user for whom an administrator needs to add an alias:

curl -u username:password -X PUT -G -d user=john -d email=jsmith@example.com http://bitbucket-host/rest/awesome-graphs/latest/emails
CODE

When you attempt to add an email address that is already used (by another Bitbucket user or already linked as an alias), you will see the response with display name and the link to the user profile of the current owner of this alias: 

{"name": "User", "link": "http://bitbucket-host/users/user"}
CODE

Deleting aliases

The curl command for deleting an alias needs to include an additional parameter 'email', which value is the email address that should be deleted from aliases.

Here is the curl command for deleting your own alias:

curl -u username:password -X DELETE -G -d email=jsmith@example.com http://bitbucket-host/rest/awesome-graphs/latest/emails
CODE

For administrators, to delete an alias of another user, the curl command is supposed to include an additional parameter 'user', which value is the username of the user whose alias an administrator needs to delete:

curl -u username:password -X DELETE -G -d user=john -d email=jsmith@example.com http://bitbucket-host/rest/awesome-graphs/latest/emails
CODE

When deleting aliases, it is not possible to delete automatically linked aliases. But when deleting an alias that was added manually or via REST API, a case insensitive search is performed that deletes all found aliases.

In case adding or deleting of aliases is successful, you will get a 200 status code to your HTTP request. When a not existing username is used, you will get a 204 status code.