# ADR-0005: API Contract Parity and SDK Deprecation Policy

**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`
