API: Groups

Groups are collections of users. They support assigning/unassigning multiple users to/from a project in one operation.

This resource does not yet have the form and schema endpoints. But as all properties are static, clients should still be able to work with this resource.

Actions

Actions

Link Description Condition
delete Deletes the group. Permission: Administrator
updateImmediately Updates the group’s attributes. Permission: Administrator

Linked Properties

Link Description Type Constraints Supported operations Condition
self This group Group not null READ  
memberships Link to collection of all the group’s memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. MemberCollection   READ Permission: view members or manage members in any project
members The list all all the users that are members of the group UserCollection   READ/WRITE Permission: manage members in any project to read & admin to write

Local Properties

Property Description Type Constraints Supported operations Condition
id Group’s id Integer x > 0 READ  
name Group’s full name, formatting depends on instance settings String   READ/WRITE Admin to write
createdAt Time of creation DateTime   READ Only visible by admins
updatedAt Time of the most recent change to the user DateTime   READ Only visible by admins

Methods

List groups

Returns a collection of groups. The client can choose to filter the groups similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain groups, for which the requesting client has sufficient permissions (view_members, manage_members).

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • id: Sort by primary key

  • created_at: Sort by group creation datetime

  • updated_at: Sort by the time the group was updated last

Default:
[["id", "asc"]]

Example:
[["id", "asc"]]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "members": [
            {
              "href": "/api/v3/users/363",
              "title": "First user"
            },
            {
              "href": "/api/v3/users/60",
              "title": "Second user"
            }
          ],
          "memberships": {
            "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
            "title": "Memberships"
          },
          "self": {
            "href": "/api/v3/groups/9",
            "title": "The group"
          }
        },
        "_type": "Group",
        "createdAt": "2015-09-23T11:06:36Z",
        "id": 9,
        "name": "The group",
        "updatedAt": "2015-09-23T11:06:36Z"
      },
      {
        "_links": {
          "members": [
            {
              "href": "/api/v3/users/343",
              "title": "Third user"
            },
            {
              "href": "/api/v3/users/60",
              "title": "Second user"
            }
          ],
          "memberships": {
            "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"123\"]}}]",
            "title": "Memberships"
          },
          "self": {
            "href": "/api/v3/groups/123",
            "title": "Another group"
          }
        },
        "_type": "Group",
        "createdAt": "2018-09-23T11:06:36Z",
        "id": 123,
        "name": "Another group",
        "updatedAt": "2019-09-23T11:06:36Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/groups"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}

List_groupsModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/groups"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "Group",
          "id": 9,
          "name": "The group",
          "createdAt": "2015-09-23T11:06:36Z",
          "updatedAt": "2015-09-23T11:06:36Z",
          "_links": {
            "self": {
              "href": "/api/v3/groups/9",
              "title": "The group"
            },
            "memberships": {
              "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
              "title": "Memberships"
            },
            "members": [
              {
                "href": "/api/v3/users/363",
                "title": "First user"
              },
              {
                "href": "/api/v3/users/60",
                "title": "Second user"
              }
            ]
          }
        },
        {
          "_type": "Group",
          "id": 123,
          "name": "Another group",
          "createdAt": "2018-09-23T11:06:36Z",
          "updatedAt": "2019-09-23T11:06:36Z",
          "_links": {
            "self": {
              "href": "/api/v3/groups/123",
              "title": "Another group"
            },
            "memberships": {
              "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"123\"]}}]",
              "title": "Memberships"
            },
            "members": [
              {
                "href": "/api/v3/users/343",
                "title": "Third user"
              },
              {
                "href": "/api/v3/users/60",
                "title": "Second user"
              }
            ]
          }
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: View members or manage members in any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

Create group

Creates a new group applying the attributes provided in the body.

No parameters

201

Created

View_groupModel

{
  "type": "object",
  "example": {
    "_type": "Group",
    "id": 9,
    "name": "The group",
    "createdAt": "2015-09-23T11:06:36Z",
    "updatedAt": "2015-09-23T11:06:36Z",
    "_links": {
      "self": {
        "href": "/api/v3/groups/9",
        "title": "The group"
      },
      "delete": {
        "href": "/api/v3/group/9",
        "method": "delete"
      },
      "memberships": {
        "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
        "title": "Memberships"
      },
      "updateImmediately": {
        "href": "/api/v3/group/9",
        "method": "patch"
      },
      "members": [
        {
          "href": "/api/v3/users/363",
          "title": "First user"
        },
        {
          "href": "/api/v3/users/60",
          "title": "Second user"
        }
      ]
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name can't be blank."
}

View group

id
integer

required path

Group id

Example:
1

200

OK

{
  "_links": {
    "delete": {
      "href": "/api/v3/group/9",
      "method": "delete"
    },
    "members": [
      {
        "href": "/api/v3/users/363",
        "title": "First user"
      },
      {
        "href": "/api/v3/users/60",
        "title": "Second user"
      }
    ],
    "memberships": {
      "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
      "title": "Memberships"
    },
    "self": {
      "href": "/api/v3/groups/9",
      "title": "The group"
    },
    "updateImmediately": {
      "href": "/api/v3/group/9",
      "method": "patch"
    }
  },
  "_type": "Group",
  "createdAt": "2015-09-23T11:06:36Z",
  "id": 9,
  "name": "The group",
  "updatedAt": "2015-09-23T11:06:36Z"
}

View_groupModel

{
  "type": "object",
  "example": {
    "_type": "Group",
    "id": 9,
    "name": "The group",
    "createdAt": "2015-09-23T11:06:36Z",
    "updatedAt": "2015-09-23T11:06:36Z",
    "_links": {
      "self": {
        "href": "/api/v3/groups/9",
        "title": "The group"
      },
      "delete": {
        "href": "/api/v3/group/9",
        "method": "delete"
      },
      "memberships": {
        "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
        "title": "Memberships"
      },
      "updateImmediately": {
        "href": "/api/v3/group/9",
        "method": "patch"
      },
      "members": [
        {
          "href": "/api/v3/users/363",
          "title": "First user"
        },
        {
          "href": "/api/v3/users/60",
          "title": "Second user"
        }
      ]
    }
  }
}

404

Returned if the group does not exist or if the API user does not have permission to view them.

Required permission If the user has the manage members permission in at least one project the user will be able to query all groups. If not, the user will be able to query all groups which are members in projects, he has the view members permission in.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Update group

Updates the given group by applying the attributes provided in the body.

id
integer

required path

Group id

Example:
1

200

OK

{
  "_links": {
    "delete": {
      "href": "/api/v3/group/9",
      "method": "delete"
    },
    "members": [
      {
        "href": "/api/v3/users/363",
        "title": "First user"
      },
      {
        "href": "/api/v3/users/60",
        "title": "Second user"
      }
    ],
    "memberships": {
      "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
      "title": "Memberships"
    },
    "self": {
      "href": "/api/v3/groups/9",
      "title": "The group"
    },
    "updateImmediately": {
      "href": "/api/v3/group/9",
      "method": "patch"
    }
  },
  "_type": "Group",
  "createdAt": "2015-09-23T11:06:36Z",
  "id": 9,
  "name": "The group",
  "updatedAt": "2015-09-23T11:06:36Z"
}

View_groupModel

{
  "type": "object",
  "example": {
    "_type": "Group",
    "id": 9,
    "name": "The group",
    "createdAt": "2015-09-23T11:06:36Z",
    "updatedAt": "2015-09-23T11:06:36Z",
    "_links": {
      "self": {
        "href": "/api/v3/groups/9",
        "title": "The group"
      },
      "delete": {
        "href": "/api/v3/group/9",
        "method": "delete"
      },
      "memberships": {
        "href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
        "title": "Memberships"
      },
      "updateImmediately": {
        "href": "/api/v3/group/9",
        "method": "patch"
      },
      "members": [
        {
          "href": "/api/v3/users/363",
          "title": "First user"
        },
        {
          "href": "/api/v3/users/60",
          "title": "Second user"
        }
      ]
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the membership does not exist or the client does not have sufficient permissions to see it.

Required permission If the user has the manage members permission in at least one project the user will be able to query all groups. If not, the user will be able to query all groups which are members in projects, he has the view members permission in.

Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "members"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Member is already taken."
}

Delete group

Deletes the group.

id
integer

required path

Group id

Example:
1

202

Returned if the group was successfully deleted

Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the group does not exist or the client does not have sufficient permissions to see it.

Required permission: Administrator

Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}