User group API

User groups

User groups are a way to organize team members in a project. The user group API is helpful for retrieving the team members that belong to a user group.

Structure of a group resource

The attributes of a group resource are described below, along with their data type.

groups resource xml - attributes

id: Integer; read only, system assigned unique identifier for a user group.
name: String; this is the name of the user group.
project_members: Array; list all the team members that belong to this user group. Information about each project member resource is in the next section.

Structure of a project member resource

The structure of a project member 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 fields like id are provided only as information about the user and cannot be updated through the API.

project member resource xml - attributes

id: Integer; read only, system assigned unique identifier for a user.
admin: Boolean; determines if a user is a Mingle Administrator or not, default is false.
readonly_member: Boolean; shows whether a user is read-only on the project.
user: Resource; name and login of a user who is a member of this project; both String.
project: Resource; name and identifier of the project; both String.

Get all user groups for a project

Reference

Request Method: GET
URL: /api/v2/projects/project_identifier/groups.xml
Parameters: NA

Example

GET

http://yourname:password@your.mingle.server:8080/api/v2/projects/test_project/groups.xml

Explanation

The above is an example of a GET request to a Mingle server running at your.mingle.server, port 8080. The request is made with the authorization credentials of yourname/password. The URL of /api/v2/projects/test_project/groups.xml represents the listing of all group resources for the project with identifier test_project.

Result

If you were authorized to perform the operation, and the resource was available, you should get an xml document that looks something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<groups type="array">
  <group>
    <id type="integer">6</id>
    <name>BAs</name>
    <projects_members type="array">
      <projects_member>
        <id type="integer">9</id>
        <admin type="boolean">false</admin>
        <readonly_member type="boolean">false</readonly_member>
        <user url="http://localhost:8080/mingle/api/v2/users/5.xml">
          <name>Thomas</name>
          <login>thomas</login>
        </user>
        <project url="http://localhost:8080/mingle/api/v2/projects/test_project.xml">
          <name>test project</name>
          <identifier>test_project</identifier>
        </project>
      </projects_member>
    </projects_members>
  </group>
  ...
  <group>
    <id type="integer">7</id>
    <name>Developers</name>
    <projects_members type="array">
      <projects_member>
        <id type="integer">7</id>
        <admin type="boolean">false</admin>
        <readonly_member type="boolean">false</readonly_member>
        <user url="http://localhost:8080/mingle/api/v2/users/6.xml">
          <name>James</name>
          <login>james</login>
        </user>
        <project url="http://localhost:8080/mingle/api/v2/projects/test_project.xml">
          <name>test project</name>
          <identifier>test_project</identifier>
        </project>
      </projects_member>
      <projects_member>
        <id type="integer">7</id>
        <admin type="boolean">false</admin>
        <readonly_member type="boolean">false</readonly_member>
        <user url="http://localhost:8080/mingle/api/v2/users/7.xml">
          <name>Kenneth</name>
          <login>kenneth</login>
        </user>
        <project url="http://localhost:8080/mingle/api/v2/projects/test_project.xml">
          <name>test project</name>
          <identifier>test_project</identifier>
        </project>
      </projects_member>
    </projects_members>
  </group>
</groups>

Get a single user group for a project