Status: Accepted
Date: 2026-02-22
Authors: Isis API Platform, Isis SDK Engineering
Reviewers: @oshun/isis-team, @oshun/core-team
Context and Problem Statement#
@isis/client intentionally exposes a broad high-level surface. After F15-003
and F15-004, remaining route gaps are limited to nine WorkflowsResource
signatures:
POST /api/v1/workflows/importGET /api/v1/workflows/:id/exportGET /api/v1/templates/featuredGET /api/v1/workflows/:id/statsPOST /api/v1/workflows/:id/starDELETE /api/v1/workflows/:id/starPOST /api/v1/workflows/:id/runGET /api/v1/workflows/:id/executionsGET /api/v1/workflows/:id/executions/:executionId
F15-005 requires an explicit decision for each gap: implement server endpoint
or deprecate/remove SDK method.
Decision#
Adopt an implement-first parity policy for this remediation cycle:
- All remaining missing
@isis/clientsignatures are retained and mapped to concrete server endpoints. - No SDK method removals or deprecations are approved in
F15.
Decision Drivers#
- Isis has a stated “no feature missed” parity objective for API, SDK, and web app surfaces.
- The missing methods represent core workflow lifecycle capabilities, not experimental or legacy-only flows.
- Deprecation would introduce avoidable client breakage and contradict the current parity remediation charter.
- Remaining gaps are bounded and implementable within the active parity workstream.
Decision Matrix#
| SDK Method | Endpoint Signature | Decision | Rationale |
|---|---|---|---|
import() |
POST /api/v1/workflows/import |
Implement | Required workflow portability capability |
export() |
GET /api/v1/workflows/:id/export |
Implement | Required workflow portability capability |
getFeaturedTemplates() |
GET /api/v1/templates/featured |
Implement | Required discovery experience |
getStats() |
GET /api/v1/workflows/:id/stats |
Implement | Required analytics surface |
star() |
POST /api/v1/workflows/:id/star |
Implement | Required social/discovery signal |
unstar() |
DELETE /api/v1/workflows/:id/star |
Implement | Required social/discovery signal |
run() |
POST /api/v1/workflows/:id/run |
Implement | Required direct workflow execution API |
getExecutionHistory() |
GET /api/v1/workflows/:id/executions |
Implement | Required run observability |
getExecution() |
GET /api/v1/workflows/:id/executions/:executionId |
Implement | Required run observability |
Consequences#
Positive#
- Preserves SDK compatibility guarantees while parity is being closed.
- Aligns backend/API roadmap with existing client contract.
- Keeps downstream SDK users off breaking-change migration paths.
Tradeoffs#
- Requires additional workflow-registry endpoint implementation work.
- Adds short-term API surface expansion before OpenAPI generation is completed.
Deprecation Governance Rule (Forward-Looking)#
Future SDK method deprecation/removal is allowed only when all conditions are met:
- replacement endpoint/method exists and is documented,
- method is marked deprecated across SDK + OpenAPI for at least one minor release,
- migration notes and upgrade path are published,
- contract-breaking CI gates are updated and approved by
@oshun/core-team.
Ticket Traceability#
F15-005ISIS-0152
References#
docs/domains/isis/remediation/ISIS_CLIENT_ROUTE_INVENTORY.mddocs/domains/isis/remediation/ISIS_REMEDIATION_BACKLOG.mdISIS_TODOS.md