kubeflow / kubeflow/notebooks

[TASK] Agree on architecture/implementation details for Bulk API endpoints

Open
#889 2 comments 0 reactions 0 assignees View on GitHub
area/backend area/v2 kind/plan-task
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.