GeneralBots/botserver
2
1
Fork 0
Code Issues Pull requests Projects Releases 323 Packages Wiki Activity Actions
botserver/docs/src/chapter-10-api/group-membership.md

10 KiB
Raw Blame History

Group Membership API

BotServer provides RESTful endpoints for managing user groups, team memberships, and collaborative workspaces.

Overview

The Group Membership API enables:

  • Group creation and management
  • Member addition and removal
  • Role assignments within groups
  • Permission inheritance
  • Team collaboration features
  • Workspace organization

Base URL

http://localhost:8080/api/v1/groups

Authentication

All Group Membership API requests require authentication:

Authorization: Bearer <token>

Endpoints

Create Group

POST /groups

Create a new group or team.

Request Body:

{
  "name": "Engineering Team",
  "description": "Product engineering team",
  "type": "team",
  "visibility": "private",
  "settings": {
    "allow_join_requests": true,
    "require_approval": true,
    "max_members": 50
  },
  "permissions": ["bot.use", "kb.read", "reports.view"]
}

Response:

{
  "group_id": "grp_abc123",
  "name": "Engineering Team",
  "type": "team",
  "created_at": "2024-01-15T10:00:00Z",
  "created_by": "usr_admin",
  "member_count": 0
}

Get Group

GET /groups/{group_id}

Retrieve group information.

Response:

{
  "group_id": "grp_abc123",
  "name": "Engineering Team",
  "description": "Product engineering team",
  "type": "team",
  "visibility": "private",
  "member_count": 12,
  "created_at": "2024-01-15T10:00:00Z",
  "settings": {
    "allow_join_requests": true,
    "require_approval": true,
    "max_members": 50
  },
  "permissions": ["bot.use", "kb.read", "reports.view"]
}

Update Group

PATCH /groups/{group_id}

Update group information.

Request Body:

{
  "name": "Engineering & DevOps Team",
  "description": "Combined engineering and operations team",
  "settings": {
    "max_members": 75
  }
}

Delete Group

DELETE /groups/{group_id}

Delete a group (requires admin permissions).

Response:

{
  "deleted": true,
  "group_id": "grp_abc123",
  "members_removed": 12
}

List Groups

GET /groups

List all groups with filtering.

Query Parameters:

  • type - Filter by group type: team, department, project
  • visibility - Filter by visibility: public, private
  • member - Filter groups containing specific user
  • search - Search in name and description
  • page - Page number (default: 1)
  • limit - Items per page (default: 20)

Response:

{
  "groups": [
    {
      "group_id": "grp_abc123",
      "name": "Engineering Team",
      "type": "team",
      "member_count": 12,
      "visibility": "private"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 20
}

Member Management

Add Member

POST /groups/{group_id}/members

Add a member to a group.

Request Body:

{
  "user_id": "usr_xyz789",
  "role": "member",
  "permissions": ["read", "write"],
  "notify": true
}

Response:

{
  "membership_id": "mem_123",
  "group_id": "grp_abc123",
  "user_id": "usr_xyz789",
  "role": "member",
  "joined_at": "2024-01-15T10:30:00Z"
}

Bulk Add Members

POST /groups/{group_id}/members/bulk

Add multiple members at once.

Request Body:

{
  "members": [
    {"user_id": "usr_001", "role": "admin"},
    {"user_id": "usr_002", "role": "member"},
    {"user_id": "usr_003", "role": "member"}
  ],
  "notify_all": true
}

Response:

{
  "added": 3,
  "failed": 0,
  "memberships": [
    {"user_id": "usr_001", "status": "added"},
    {"user_id": "usr_002", "status": "added"},
    {"user_id": "usr_003", "status": "added"}
  ]
}

List Members

GET /groups/{group_id}/members

List group members.

Query Parameters:

  • role - Filter by role
  • status - Filter by status: active, pending, suspended
  • search - Search in member names
  • page - Page number
  • limit - Items per page

Response:

{
  "members": [
    {
      "membership_id": "mem_123",
      "user": {
        "user_id": "usr_xyz789",
        "username": "johndoe",
        "full_name": "John Doe",
        "avatar_url": "https://example.com/avatar.jpg"
      },
      "role": "admin",
      "status": "active",
      "joined_at": "2024-01-15T10:30:00Z",
      "last_active": "2024-01-15T14:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

Update Member Role

PATCH /groups/{group_id}/members/{user_id}

Update a member's role or permissions.

Request Body:

{
  "role": "admin",
  "permissions": ["read", "write", "delete"]
}

Remove Member

DELETE /groups/{group_id}/members/{user_id}

Remove a member from a group.

Response:

{
  "removed": true,
  "group_id": "grp_abc123",
  "user_id": "usr_xyz789",
  "removed_at": "2024-01-15T15:00:00Z"
}

Group Roles

List Roles

GET /groups/{group_id}/roles

List available roles in a group.

Response:

{
  "roles": [
    {
      "role_id": "owner",
      "name": "Owner",
      "permissions": ["all"],
      "member_count": 1
    },
    {
      "role_id": "admin",
      "name": "Administrator",
      "permissions": ["manage_members", "manage_settings", "read", "write"],
      "member_count": 2
    },
    {
      "role_id": "member",
      "name": "Member",
      "permissions": ["read", "write"],
      "member_count": 9
    }
  ]
}

Create Custom Role

POST /groups/{group_id}/roles

Create a custom role for a group.

Request Body:

{
  "name": "Moderator",
  "permissions": ["read", "write", "moderate"],
  "description": "Can moderate content and manage posts"
}

Join Requests

Request to Join

POST /groups/{group_id}/join-requests

Request to join a private group.

Request Body:

{
  "message": "I would like to join the engineering team",
  "referred_by": "usr_admin"
}

Response:

{
  "request_id": "req_456",
  "group_id": "grp_abc123",
  "user_id": "usr_xyz789",
  "status": "pending",
  "submitted_at": "2024-01-15T10:00:00Z"
}

List Join Requests

GET /groups/{group_id}/join-requests

List pending join requests (admin only).

Response:

{
  "requests": [
    {
      "request_id": "req_456",
      "user": {
        "user_id": "usr_xyz789",
        "username": "newuser",
        "full_name": "New User"
      },
      "message": "I would like to join the engineering team",
      "status": "pending",
      "submitted_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 3
}

Approve/Reject Request

PATCH /groups/{group_id}/join-requests/{request_id}

Process a join request.

Request Body:

{
  "action": "approve",
  "role": "member",
  "note": "Welcome to the team!"
}

Group Invitations

Send Invitation

POST /groups/{group_id}/invitations

Invite users to join a group.

Request Body:

{
  "emails": ["user1@example.com", "user2@example.com"],
  "role": "member",
  "message": "You're invited to join our team!",
  "expires_in_days": 7
}

Response:

{
  "invitations": [
    {
      "invitation_id": "inv_789",
      "email": "user1@example.com",
      "status": "sent",
      "expires_at": "2024-01-22T10:00:00Z"
    }
  ],
  "sent": 2,
  "failed": 0
}

Accept Invitation

POST /invitations/{invitation_id}/accept

Accept a group invitation.

Response:

{
  "membership_id": "mem_999",
  "group_id": "grp_abc123",
  "joined_at": "2024-01-15T11:00:00Z"
}

Group Permissions

Get Group Permissions

GET /groups/{group_id}/permissions

List group permissions.

Response:

{
  "permissions": [
    {
      "permission": "bot.use",
      "description": "Use bots",
      "inherited_from": null
    },
    {
      "permission": "kb.read",
      "description": "Read knowledge base",
      "inherited_from": "parent_group"
    }
  ]
}

Update Permissions

PATCH /groups/{group_id}/permissions

Update group permissions.

Request Body:

{
  "add": ["reports.create", "analytics.view"],
  "remove": ["kb.write"]
}

Hierarchical Groups

Create Subgroup

POST /groups/{parent_id}/subgroups

Create a subgroup under a parent group.

Request Body:

{
  "name": "Frontend Team",
  "inherit_permissions": true,
  "inherit_members": false
}

List Subgroups

GET /groups/{group_id}/subgroups

List all subgroups.

Response:

{
  "subgroups": [
    {
      "group_id": "grp_sub123",
      "name": "Frontend Team",
      "member_count": 5,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 2
}

Group Analytics

Get Group Analytics

GET /groups/{group_id}/analytics

Get group activity analytics.

Response:

{
  "group_id": "grp_abc123",
  "analytics": {
    "member_growth": {
      "current": 12,
      "last_month": 10,
      "growth_rate": 0.20
    },
    "activity": {
      "messages_sent": 456,
      "tasks_completed": 23,
      "avg_response_time": 3600
    },
    "engagement": {
      "active_members": 10,
      "engagement_rate": 0.83
    }
  },
  "period": "30d"
}

Error Responses

403 Forbidden

{
  "error": "permission_denied",
  "message": "You don't have permission to manage this group"
}

409 Conflict

{
  "error": "member_exists",
  "message": "User is already a member of this group"
}

422 Unprocessable Entity

{
  "error": "group_full",
  "message": "Group has reached maximum member limit",
  "max_members": 50,
  "current_members": 50
}

Best Practices

  1. Use Descriptive Names: Group names should clearly indicate purpose
  2. Set Member Limits: Prevent groups from becoming too large
  3. Regular Cleanup: Remove inactive members periodically
  4. Permission Inheritance: Use hierarchy for easier management
  5. Document Purpose: Always include group descriptions
  6. Review Requests: Don't auto-approve join requests for sensitive groups

Related APIs