Groups

Note

The Groups API can currently only be used by Administrator users.

Listing Groups

GET /api2/groups
Query Parameters:
 
  • display_name (optional) – Filter for groups by display name. It must be an exact match to be returned.
  • user_id (optional) – Filter for groups that the specified user has permissions in.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items" : [
    {
      "id": "3",
      "display_name": "My Group",
      "created_on": "2012-11-09T12:02:47Z",
      "modified_on": "2013-01-18T02:38:48Z",
      "links": {
        "self": "/api2/groups/3",
        "users": "/api2/users?group_id=3",
      }
    },
    {
      "id": "4",
      "display_name": "Someones Group",
      "created_on": "2012-11-09T12:02:47Z",
      "modified_on": "2013-01-18T02:38:48Z",
      "links": {
        "self": "/api2/groups/4",
        "users": "/api2/users?group_id=4"
      }
    }
  ]
}

Fetching a Group

GET /api2/groups/(group_id)

Fetch an individual group by its unique ID.

Example Response:

HTTP/1.1 200 OK
Content-type: application/json

{
   "id": "3",
   "display_name": "My Group",
   "created_on": "2012-11-09T12:02:47Z",
   "modified_on": "2013-01-18T02:38:48Z",
   "links": {
     "self": "/api2/groups/3",
     "users": "/api2/users?group_id=3"
   }
}
GET /api2/groups/public

Fetch the public group.

Example Response:

HTTP/1.1 200 OK
Content-type: application/json

{
   "id": "1",
   "display_name": "Public",
   "created_on": "2012-11-09T12:02:47Z",
   "modified_on": "2013-01-18T02:38:48Z",
   "links": {
     "self": "/api2/groups/1",
     "users": "/api2/users?group_id=1"
   }
}
GET /api2/groups/registered-users

Fetch the registered-users group.

Example Response:

HTTP/1.1 200 OK
Content-type: application/json

{
   "id": "2",
   "display_name": "Registered Users",
   "created_on": "2012-11-09T12:02:47Z",
   "modified_on": "2013-01-18T02:38:48Z",
   "links": {
     "self": "/api2/groups/2",
     "users": "/api2/users?group_id=2"
   }
}

Creating a Group

POST /api2/groups

Add a new group.

Json Parameters:
 
  • display_name (required) – The user-facing name for this group.

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /api2/groups/2

{
  "id": "2",
  "display_name": "Students",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "links": {
    "self": "/api2/groups/2",
    "users": "/api2/users?group_id=2"
  }
}

Updating a Group

POST /api2/groups
Json Parameters:
 
  • display_name (optional) – Updates the group’s display name.
POST /api2/groups/123/add-users
Json Parameters:
 
  • user_ids (required) – A JSON list of Users to be added to this group.
POST /api2/groups/123/remove-users
Json Parameters:
 
  • user_ids (required) – A JSON list of Users to be removed from this group.

Deleting a Group

DELETE /api2/groups/(group_id)

Delete a group.

This endpoint is idempotent; attempting to delete a group that does not exist will return a successful response.

Example Response:

HTTP/1.1 204 No Content

Previous topic

Users

Next topic

Roles

This Page