Eve library

ADR-0005: API Contract Parity and SDK Deprecation Policy

ADR

Revision 1

On this page

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/import
  • GET /api/v1/workflows/:id/export
  • GET /api/v1/templates/featured
  • GET /api/v1/workflows/:id/stats
  • POST /api/v1/workflows/:id/star
  • DELETE /api/v1/workflows/:id/star
  • POST /api/v1/workflows/:id/run
  • GET /api/v1/workflows/:id/executions
  • GET /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/client signatures 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:

  1. replacement endpoint/method exists and is documented,
  2. method is marked deprecated across SDK + OpenAPI for at least one minor release,
  3. migration notes and upgrade path are published,
  4. contract-breaking CI gates are updated and approved by @oshun/core-team.

Ticket Traceability#

  • F15-005
  • ISIS-0152

References#

  • docs/domains/isis/remediation/ISIS_CLIENT_ROUTE_INVENTORY.md
  • docs/domains/isis/remediation/ISIS_REMEDIATION_BACKLOG.md
  • ISIS_TODOS.md