Groups API

List groups

List all the authenticated user’s groups including owned groups and member groups.

GET /api/v1/groups.json

Response:

{
  "groups": [
    {
      "id": "group id",
      "uname": "group uname",
      "own_projects_count": "count of own projects",
      "created_at": "group created at",
      "updated_at": "group updated_at",
      "description": "group description",
      "owner": {
        "id": "owner id",
        "name": "owner name",
        "type": "owner type",
        "url": "path to owner data"
      },
      "avatar_url": "avatar url",
      "html_url": "html group path",
      "url": "api group path"
    }
  ],
  "url": "path to groups data"
}

Example:

{
  "groups": [
    {
      "id": 1,
      "uname": "rosa",
      "own_projects_count": 5,
      "created_at": 1349357795,
      "updated_at": 1349358084,
      "description": "public group",
      "owner": {
        "id": 5,
        "name": "Timothy Bobrov1",
        "type": "User",
        "url": "/api/v1/users/5.json"
      },
      "avatar_url": "avatar url",
      "html_url": "/rosa",
      "url": "/api/v1/groups/1.json"
    }
  ],
  "url": "/api/v1/groups.json"
}

Get a single group

GET /api/v1/groups/:id.json

Parameters:

id
Required Integer identifier of current group.

Response:

{
  "group": {
    "id": "group id",
    "uname": "group uname",
    "own_projects_count": "count of own projects",
    "created_at": "group created at",
    "updated_at": "group updated_at",
    "description": "group description",
    "owner": {
      "id": "owner id",
      "name": "owner name",
      "type": "owner type",
      "url": "path to owner data"
    },
    "avatar_url": "avatar url",
    "html_url": "html group path",
    "url": "api group path"
  }
}

Example:

{
  "group": {
    "id": 1,
    "uname": "rosa",
    "own_projects_count": 5,
    "created_at": 1349357795,
    "updated_at": 1349358084,
    "description": "public group",
    "owner": {
      "id": 5,
      "name": "Timothy Bobrov1",
      "type": "User",
      "url": "/api/v1/users/5.json"
    },
    "avatar_url": "avatar url",
    "html_url": "/rosa",
    "url": "/api/v1/groups/1.json"
  }
}

Update a single group

PUT /api/v1/groups/:id.json

Parameters:

id
Required Integer identifier of current group.

Input:

description:
Optional String group description.

Request:

{
  "group": {
    "description": "group description"
  }
}

Response:

{
  "group": {
    "id": "group id (null if failed)",
    "message": "success or fail message"
  }
}

Example:

{
  "group": {
    "id": 56,
    "message": "Group has been updated successfully"
  }
}

Create group

POST /api/v1/groups.json

Input:

uname:
Required String group uname.
description:
Optional String group description.

Request:

{
  "group": {
    "uname": "group uname",
    "description": "group description"
  }
}

Response:

{
  "group": {
    "id": "group id (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "group": {
    "id": 56,
    "message": "Group has been created successfully"
  }
}

Destroy group

DELETE /api/v1/groups/:id.json

Parameters:

id
Required Integer identifier of current group.

Request example:

/api/v1/groups/54.json

Response:

{
  "group": {
    "id": "group id (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "group": {
    "id": 56,
    "message": "Group has been destroyed successfully"
  }
}

Members of a single group

GET /api/v1/groups/:id/members.json

Parameters:

id
Required Integer identifier of current group.

Response:

{
  "group": {
    "id": "group id",
    "members": [
      {
        "id": "member id",
        "type": "only User may be member of group",
        "url": "user path"
      }
    ]
  },
  "url": "members path"
}

Example:

{
  "group": {
    "id": 77,
    "members": [
      {
        "id": 31,
        "type": "User",
        "url": "/api/v1/users/31.json"
      },
      {
        "id": 22,
        "type": "User",
        "url": "/api/v1/users/22.json"
      }
    ]
  },
  "url": "/api/v1/groups/77/members.json"
}

Add member to a single group

PUT /api/v1/groups/:id/add_member.json

Parameters:

id
Required Integer identifier of current group.

Input:

member_id
Required Integer identifier of new member (may be added only User).
role
Optional String role for new member (reader/writer/admin), by default admin.

Request:

{
  "member_id": 34,
  "role": "admin"
}

Response:

{
  "group": {
    "id": "group id (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "group": {
    "id": 56,
    "message": "User '34' has been added to group successfully"
  }
}

Remove member from a single group

DELETE /api/v1/groups/:id/remove_member.json

Parameters:

id
Required Integer identifier of current group.

Input:

member_id
Required Integer identifier of member (may be removed only User).

Request:

{
  "member_id": 34
}

Response:

{
  "group": {
    "id": "group id (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "group": {
    "id": 56,
    "message": "User '32' has been removed from group successfully"
  }
}

Update member role for a single group

PUT /api/v1/groups/:id/update_member.json

Parameters:

id
Required Integer identifier of current group.

Input:

member_id
Required Integer identifier of member.
role
Required String new role for member (reader, writer, admin).

Request:

{
  "member_id": 34,
  "role": "admin"
}

Response:

{
  "group": {
    "id": "group id (null if failed)",
    "message": "success or fail message"
  }
}

Examples:

{
  "group": {
    "id": 56,
    "message": "Role for user '34' has been updated in group successfully"
  }
}