Initial commit
This commit is contained in:
Zhongwei Li
293
skills/protocolsio-integration/references/workspaces.md
Normal file
293
skills/protocolsio-integration/references/workspaces.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# Workspaces API
|
||||
|
||||
## Overview
|
||||
|
||||
Workspaces in protocols.io enable team collaboration by organizing protocols, managing members, and controlling access permissions. The Workspaces API allows you to list workspaces, manage memberships, and access workspace-specific protocols.
|
||||
|
||||
## Base URL
|
||||
|
||||
All workspace endpoints use the base URL: `https://protocols.io/api/v3`
|
||||
|
||||
## Workspace Operations
|
||||
|
||||
### List User Workspaces
|
||||
|
||||
Retrieve all workspaces the authenticated user has access to.
|
||||
|
||||
**Endpoint:** `GET /workspaces`
|
||||
|
||||
**Query Parameters:**
|
||||
- `page_size`: Number of results per page (default: 10, max: 50)
|
||||
- `page_id`: Page number for pagination (starts at 0)
|
||||
|
||||
**Response includes:**
|
||||
- Workspace ID and name
|
||||
- Workspace type (personal, group, institutional)
|
||||
- Member count
|
||||
- Access level (owner, admin, member, viewer)
|
||||
- Creation date
|
||||
|
||||
**Example Request:**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
||||
"https://protocols.io/api/v3/workspaces"
|
||||
```
|
||||
|
||||
### Get Workspace Details
|
||||
|
||||
Retrieve detailed information about a specific workspace.
|
||||
|
||||
**Endpoint:** `GET /workspaces/{workspace_id}`
|
||||
|
||||
**Path Parameters:**
|
||||
- `workspace_id`: The workspace's unique identifier
|
||||
|
||||
**Response includes:**
|
||||
- Complete workspace metadata
|
||||
- Member list with roles
|
||||
- Workspace settings and permissions
|
||||
- Protocol count and categories
|
||||
|
||||
## Workspace Membership
|
||||
|
||||
### List Workspace Members
|
||||
|
||||
Retrieve all members of a workspace.
|
||||
|
||||
**Endpoint:** `GET /workspaces/{workspace_id}/members`
|
||||
|
||||
**Query Parameters:**
|
||||
- `page_size`: Number of results per page
|
||||
- `page_id`: Page number for pagination
|
||||
|
||||
**Response includes:**
|
||||
- Member name and email
|
||||
- Role (owner, admin, member, viewer)
|
||||
- Join date
|
||||
- Activity status
|
||||
|
||||
### Request Workspace Access
|
||||
|
||||
Request to join a workspace.
|
||||
|
||||
**Endpoint:** `POST /workspaces/{workspace_id}/join-request`
|
||||
|
||||
**Request Body:**
|
||||
- `message` (optional): Message to workspace admins explaining the request
|
||||
|
||||
**Example Request:**
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "I am collaborating with Dr. Smith on the CRISPR project and would like to access the shared protocols."
|
||||
}' \
|
||||
"https://protocols.io/api/v3/workspaces/12345/join-request"
|
||||
```
|
||||
|
||||
### Join Public Workspace
|
||||
|
||||
Directly join a public workspace without approval.
|
||||
|
||||
**Endpoint:** `POST /workspaces/{workspace_id}/join`
|
||||
|
||||
**Note**: Only available for workspaces configured to allow public joining
|
||||
|
||||
## Workspace Protocols
|
||||
|
||||
### List Workspace Protocols
|
||||
|
||||
Retrieve all protocols in a workspace.
|
||||
|
||||
**Endpoint:** `GET /workspaces/{workspace_id}/protocols`
|
||||
|
||||
**Query Parameters:**
|
||||
- `filter`: Filter protocols
|
||||
- `all`: All protocols in the workspace
|
||||
- `own`: Only protocols you created
|
||||
- `shared`: Protocols shared with you
|
||||
- `key`: Search keywords
|
||||
- `order_field`: Sort field (`activity`, `created_on`, `modified_on`, `name`)
|
||||
- `order_dir`: Sort direction (`desc`, `asc`)
|
||||
- `page_size`: Number of results per page
|
||||
- `page_id`: Page number for pagination
|
||||
- `content_format`: Content format (`json`, `html`, `markdown`)
|
||||
|
||||
**Example Request:**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
||||
"https://protocols.io/api/v3/workspaces/12345/protocols?filter=all&order_field=modified_on&order_dir=desc"
|
||||
```
|
||||
|
||||
### Create Protocol in Workspace
|
||||
|
||||
Create a new protocol within a specific workspace.
|
||||
|
||||
**Endpoint:** `POST /workspaces/{workspace_id}/protocols`
|
||||
|
||||
**Request Body**: Same parameters as standard protocol creation (see protocols_api.md)
|
||||
|
||||
**Note**: The protocol will be created within the workspace and inherit workspace permissions
|
||||
|
||||
## Workspace Types and Permissions
|
||||
|
||||
### Workspace Types
|
||||
|
||||
1. **Personal Workspace**
|
||||
- Default workspace for individual users
|
||||
- Private by default
|
||||
- Can share specific protocols
|
||||
|
||||
2. **Group Workspace**
|
||||
- Collaborative workspace for teams
|
||||
- Shared access for all members
|
||||
- Role-based permissions
|
||||
|
||||
3. **Institutional Workspace**
|
||||
- Organization-wide workspace
|
||||
- Often includes branding
|
||||
- Centralized protocol management
|
||||
|
||||
### Permission Levels
|
||||
|
||||
1. **Owner**
|
||||
- Full workspace control
|
||||
- Manage members and permissions
|
||||
- Delete workspace
|
||||
|
||||
2. **Admin**
|
||||
- Manage protocols and members
|
||||
- Configure workspace settings
|
||||
- Cannot delete workspace
|
||||
|
||||
3. **Member**
|
||||
- Create and edit protocols
|
||||
- View all workspace protocols
|
||||
- Comment and collaborate
|
||||
|
||||
4. **Viewer**
|
||||
- View-only access
|
||||
- Can comment on protocols
|
||||
- Cannot create or edit
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Lab Protocol Repository
|
||||
|
||||
Organize lab protocols in a shared workspace:
|
||||
|
||||
1. Create or join lab workspace: `GET /workspaces`
|
||||
2. List existing protocols: `GET /workspaces/{id}/protocols`
|
||||
3. Create new protocols: `POST /workspaces/{id}/protocols`
|
||||
4. Invite lab members: Share workspace invitation
|
||||
5. Organize by categories or tags
|
||||
|
||||
### 2. Collaborative Protocol Development
|
||||
|
||||
Develop protocols with team members:
|
||||
|
||||
1. Identify target workspace: `GET /workspaces`
|
||||
2. Create draft protocol in workspace
|
||||
3. Share with team members automatically via workspace
|
||||
4. Gather feedback through comments
|
||||
5. Iterate and publish final version
|
||||
|
||||
### 3. Cross-Institutional Collaboration
|
||||
|
||||
Work with external collaborators:
|
||||
|
||||
1. Create or identify shared workspace
|
||||
2. Request access: `POST /workspaces/{id}/join-request`
|
||||
3. Once approved, access shared protocols
|
||||
4. Contribute new protocols or updates
|
||||
5. Maintain institutional protocol copies in personal workspace
|
||||
|
||||
### 4. Protocol Migration
|
||||
|
||||
Move protocols between workspaces:
|
||||
|
||||
1. List source workspace protocols: `GET /workspaces/{source_id}/protocols`
|
||||
2. For each protocol, retrieve full details
|
||||
3. Create protocol in target workspace: `POST /workspaces/{target_id}/protocols`
|
||||
4. Copy all steps and metadata
|
||||
5. Update references and links
|
||||
|
||||
### 5. Workspace Audit
|
||||
|
||||
Review workspace activity and content:
|
||||
|
||||
1. List all workspaces: `GET /workspaces`
|
||||
2. For each workspace, get member list
|
||||
3. Retrieve protocol lists with activity dates
|
||||
4. Identify inactive or outdated protocols
|
||||
5. Generate activity reports
|
||||
|
||||
## Workspace Management Best Practices
|
||||
|
||||
1. **Organization**
|
||||
- Use consistent naming conventions
|
||||
- Tag protocols by project or category
|
||||
- Maintain workspace directory or index
|
||||
|
||||
2. **Access Control**
|
||||
- Review member list regularly
|
||||
- Assign appropriate permission levels
|
||||
- Remove inactive members
|
||||
|
||||
3. **Protocol Standards**
|
||||
- Establish workspace-wide protocol templates
|
||||
- Define required metadata fields
|
||||
- Implement quality review process
|
||||
|
||||
4. **Collaboration**
|
||||
- Communicate workspace guidelines to members
|
||||
- Encourage protocol documentation
|
||||
- Facilitate knowledge sharing
|
||||
|
||||
5. **Backup and Archival**
|
||||
- Regularly export workspace protocols
|
||||
- Maintain protocol version history
|
||||
- Archive completed projects
|
||||
|
||||
## Organizations and Workspaces
|
||||
|
||||
Organizations are higher-level entities that can contain multiple workspaces.
|
||||
|
||||
### Export Organization Data
|
||||
|
||||
**Endpoint:** `GET /organizations/{org_id}/export`
|
||||
|
||||
**Use case**: Bulk export of all protocols and workspace data for institutional archives or backups
|
||||
|
||||
## Notifications and Activity
|
||||
|
||||
Workspace activity may trigger notifications:
|
||||
|
||||
- New protocols added to workspace
|
||||
- Protocol updates by team members
|
||||
- New comments on workspace protocols
|
||||
- Member joins or leaves workspace
|
||||
- Permission changes
|
||||
|
||||
Configure notification preferences in account settings.
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common error responses:
|
||||
|
||||
- `400 Bad Request`: Invalid workspace ID or parameters
|
||||
- `401 Unauthorized`: Missing or invalid access token
|
||||
- `403 Forbidden`: Insufficient workspace permissions
|
||||
- `404 Not Found`: Workspace not found or no access
|
||||
- `429 Too Many Requests`: Rate limit exceeded
|
||||
|
||||
## Integration Considerations
|
||||
|
||||
When integrating workspace functionality:
|
||||
|
||||
1. **Cache workspace list**: Avoid repeated workspace list calls
|
||||
2. **Respect permissions**: Check user's role before attempting operations
|
||||
3. **Handle join requests**: Implement workflow for workspace access approval
|
||||
4. **Sync regularly**: Update local workspace data periodically
|
||||
5. **Support offline access**: Cache protocols for offline work with sync on reconnection
|
||||
Reference in New Issue
Block a user