migrate-api-to-graphql-client

name	migrate-api-to-graphql-client
description	Migrate the REST client path to a GraphQL client architecture with typed operations and incremental rollout.

Migrate API to GraphQL Client Path

Use this skill when a task asks to move from REST-first client calls to a GraphQL client model.

Goal

Introduce a GraphQL client path that can coexist with current REST endpoints during migration, then progressively replace REST usage.

Migration Principles

• Do not break existing auth/session behavior during rollout.
• Keep migration incremental: one feature domain at a time.
• Treat GraphQL as the new data contract layer while REST stays as fallback until parity is complete.

Files To Update

1) GraphQL client foundation

• Add a GraphQL client dependency (for example: Apollo Client, urql, or graphql-request) based on task constraints.
• Add shared client initialization under src/client/data/ (for example: graphql-client.ts).
• Configure credential handling for cookie-based auth where needed.

2) Schema and operation organization

• Add a clear folder layout for operations/fragments/types (for example: src/client/data/graphql/).
• Keep operation names domain-oriented and stable.
• Prefer generated TypeScript types when codegen is available.

3) Feature rollout

• Create feature-level adapters/hooks that hide transport details from components.
• Migrate domain by domain (auth/session first if requested, then product/preferences, etc.).
• Keep equivalent behavior with current REST flows while both paths coexist.

4) REST deprecation plan

• Document which REST endpoints are superseded.
• Keep compatibility endpoints active until all consuming code is migrated.
• Remove legacy code only after tests prove GraphQL parity.

5) Docs and changelog

• Update docs/API.md with GraphQL migration status and contract guidance.
• Update docs/ARCHITECTURE.md when transport/data layers change.
• Add migration notes under CHANGELOG.md → Unreleased.

Validation Checklist

• Run npm run lint
• Run npm run type-check
• Run focused E2E tests for migrated feature paths
• Verify auth/session cookies still work correctly with GraphQL requests
• Verify GraphQL errors are surfaced via existing error handling patterns

Done Criteria

• GraphQL client path is established with a documented migration plan.
• At least one feature path is migrated without regression.
• REST compatibility strategy is explicit and time-bounded.
• Docs/changelog reflect architecture and workflow updates.