Help

User resources are located by issuing a GET request to the server with the users id a parameter. You can get an individual users id by looking up a project's team list which returns a list of user resources, including the id for each user. All updates of a user use the id. If you would like to update the value of a user property, you would use the id, as with updating an individual user's attribute.

Before you manipulate user using the API, we recommend that familiarize yourself with some key concepts dealing with users and user property definitions.

Users are a static entities. The structure of a user resource, and its attributes are described below, along with their data type. Also included with each attribute is whether you are allowed to update the value. System generated field like id are provided only as information about the card and cannot be updated through the API.

user resource xml - attributes

• id: Integer; read only, system assigned unique identifier for a user - use this to get a identifier uniquely.
• login: String; the Mingle login name for the user.
• email: String
• name: String
• password: String, this field is not provided on a GET of a user resource.
• password_confirmation: String, must be identical to password on an update, this field is not provided on a GET of a user resource.
• admin: Boolean, determines if a user is a Mingle Administrator or not, default is false.
• activated: Boolean, determines if a user is activated in Mingle or not, default is true.
• version_control_user_name: String

Reference

        Request Method: GET
        URL: /projects/project_identifier/users.xml
        Parameters: NA
      

Example

        GET

        https://yourname:password@your.mingle.server:8080/projects/test_project/users.xml
      

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL is the location of all user resources for the project with identifier "test_project".

Result

Upon execution, you should get a xml document that looks something like the following.

<users type="array">
  <user>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <email>fred@example.com</email>
    <id type="integer">28</id>
    <login>fred</login>
    <name>Fred Flintstone</name>
    <version_control_user_name/>
  </user>
  .
  .
  .
  <user>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <email>barney@example.com</email>
    <id type="integer">29</id>
    <login>barney</login>
    <name>Barnaby Rogers</name>
    <version_control_user_name/>
  </user>
</users>
          

The attributes activated, admin and version_control_user_name will not be returned when the user trying to get team members is not project administrator or Mingle administrator.

Reference

        Request Method: GET
        URL: /users.xml
        Parameters: NA
      

Example

        GET

        https://yourname:password@your.mingle.server:8080/users.xml
      

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL is the location of all user resources for the project with identifier "test_project".

Result

Upon execution, you should get a xml document that looks exactly like a project's team member listing, except it contains details for all user resources in the system, not just for a particular ptoject. You must be a Mingle Administrator to make this call to the API.

<users type="array">
  <user>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <email>fred@example.com</email>
    <id type="integer">28</id>
    <login>fred</login>
    <name>Fred Flintstone</name>
    <version_control_user_name/>
  </user>
  .
  .
  .
  <user>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <email>barney@example.com</email>
    <id type="integer">29</id>
    <login>barney</login>
    <name>Barnaby Rogers</name>
    <version_control_user_name/>
  </user>
</users>
          

You must have Mingle administrator privileges to make this call to the API.

Reference

        Request Method: GET
        URL: /users/id.xml
        Parameters: NA
      

Example

        GET

        https://yourname:password@your.mingle.server:8080/users/42.xml
      

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL is the location of the user resource corresponding to the user with id 42 that is a member of the project with identifier "test_project".

Result

Upon execution, if you have appropriate permissions, .

<users type="array">
  <user>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <email>fred@example.com</email>
    <id type="integer">28</id>
    <login>fred</login>
    <name>Fred Flintstone</name>
    <version_control_user_name/>
  </user>
  .
  .
  .
  <user>
    <activated type="boolean">true</activated>
    <admin type="boolean">false</admin>
    <email>barney@example.com</email>
    <id type="integer">29</id>
    <login>barney</login>
    <name>Barnaby Rogers</name>
    <version_control_user_name/>
  </user>
</users>
          

You must have Mingle administrator privileges to make this call to the API.

Reference

        Request Method: POST
        URL: /users.xml
        Parameters: 
        user[name]
        user[login]
        user[email]
        user[password]
        user[password_confirmation]
        user[version_control_user_name]
        user[admin]
      

Example

        POST

        https://yourname:password@your.mingle.server:8080/users.xml
        

        user[name]=John Smith
        user[login]=john
        user[email]=jsmith@example.com
        user[password]=t0ps3cr3t.
        user[password_confirmation]=t0ps3cr3t.
        user[version_control_user_name]=jsmith
        user[admin]=false
      

Explanation

The above is an example of a POST request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL is the location of all user resources for the project with identifier "test_project". Posting the parameters creates a user with the specified values on the Mingle instance.

Result

If you have sufficient permissions to perform the action and the action was successful, you will be returned a location attribute in the header of the response, which is a url from which you can get the user resource that was created.

You must have Mingle administrator privileges to make this call to the API.

Reference

        Request Method: PUT
        URL: /users/id.xml
        Parameters: 
        user[name]
        user[login]
        user[email]
        user[password]
        user[password_confirmation]
        user[version_control_user_name]
        user[admin]
      

Example

        PUT

        https://yourname:password@your.mingle.server:8080/users/42.xml
        

        user[name]=John Smythe
        user[password]=t0ps53cr3t.
        user[password_confirmation]=t0p53cr3t.
      

Explanation

The above is an example of a PUT request to a Mingle server running at your.mingle.server, post 8080. The request is made with the authorization credentials of yourname/password. The URL is the location the user resource for the user with id 42 in that Mingle instance.

Result

If you have sufficient permissions to perform the action and the action was successful, then user with id will be updated to have a name of "John Smythe" and their password be "t0p53cr3t.". You will be returned a location attribute in the header of the response, which is a url from which you can get the user resource that was updated.

You must have Mingle administrator privileges to make this call to the API.