[TASK] Agree on architecture/implementation details for Bulk API endpoints
- Dominant language
- No language data
- Stars
- 84
- Forks
- 149
- Avg merge
- 5d 15h
- Merged PRs (30d)
- 29
Description
### Certification
- [x] I certify I am an Epic Owner for Kubeflow Notebooks 2.0 and expected to create planning-related issues.
### Description
As a community, we need to agree on how Bulk APIs will be designed and implemented across Notebooks 2.0.
Unlike resource-specific API proposals, this proposal should define a general pattern that can be applied
consistently to any resource type where bulk operations are relevant (Workspaces, Secrets, Volumes, Image
Assets, etc.).
RESTful conventions do not prescribe a standard approach for bulk operations. Common patterns include:
Frontend Orchestration:
- No dedicated bulk endpoints; frontend issues multiple individual API calls
- Simpler backend; complexity managed client-side
Dedicated Bulk Endpoints:
- Each resource type exposes a bulk operation endpoint (e.g., POST /api/v1/workspaces:bulk)
- Request body contains array of operations with action type, resource reference, and parameters
- Backend processes and returns aggregated results
Key areas requiring alignment:
- Endpoint conventions: Path structure for bulk endpoints (e.g., :bulk suffix, /batch path, or other)
- Request format: How operations are expressed in the request body (action enum, resource identifiers,
parameters)
- Response format: How results are returned (per-operation status, aggregated success/failure counts)
- Error handling: Partial failure strategy (all-or-nothing vs. best-effort with per-item results)
- Authorization: Per-item authorization checks vs. batch authorization
- Idempotency: How retries are handled safely for bulk operations
- Supported actions: Which operations are eligible for bulk (delete, update, pause/resume, etc.)
An initial proposal should be drafted and reviewed so that bulk API conventions are well-defined and can
serve as a source of truth when implementing bulk operations for any resource type.
### Acceptance Criteria
- [ ] API Proposal for Bulk API conventions is drafted as a Markdown document
- [ ] API Proposal defines a resource-agnostic pattern applicable to any resource type
- [ ] API Proposal addresses endpoint conventions, request/response format, and error handling
- [ ] API Proposal is reviewed and agreed upon by community
- [ ] API Proposal is architecturally consistent with existing v2 backend patterns
Contributor guide
Research direction
Start by reviewing the existing v2 backend patterns and the community discussion around Bulk API conventions. Draft a Markdown API proposal covering endpoint conventions, request and response formats, error handling, authorization, idempotency, and supported actions. Done means the proposal is resource-agnostic, consistent with v2 patterns, and reviewed and agreed upon by the community.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100