REST / GraphQL API連携で地味に詰まるポイントまとめ【フロントエンド実務Tips】

Posted at 2025-06-05

はじめに

フロントエンド案件でAPI連携はほぼ必須スキルですが、実務に入ると「地味に詰まるポイント」が頻繁に出てきます。しかも仕様書には書かれていない落とし穴が多い。この記事では、REST / GraphQLを中心に、実際の受託案件・企業案件でよく遭遇するAPI連携の詰まりポイントと解決策をまとめます。

想定読者

フロントエンド案件の実務を進めている方
API連携に自信を持ちたい方
単なるサンプルコード以上のリアルな実務Tipsを知りたい方

全体イメージ

Next.js (App Router構成)
TypeScript
React Query / SWR / Axios / Fetch API
OpenAPI / zodスキーマ連携
REST / GraphQL API
エラーハンドリング設計
認証フロー（Token / OAuth2 / Cookie）
CORS / SameSite / CSRF対策

1. REST API編

✅ Axios or Fetch問題

最近は fetch() 標準APIの進化で以下が標準化しつつある:

自動JSONパース不要（response.json()だけ）
SSRでもNode対応可能（Next.js内蔵）
fetch をラップして共通化するのが実務向き

ラッパー例

export async function api<T>(url: string, options?: RequestInit): Promise<T> {
  const res = await fetch(url, options);
  if (!res.ok) throw new Error("API Error");
  return res.json() as Promise<T>;
}

✅ GETでも必ず型定義を作る

interface User {
  id: number;
  name: string;
  email: string;
}

const res = await api<User>("/api/user/1");

✅ エラーハンドリングの癖

ステータスコードによるエラーマッピングを決めておく
401, 403, 404, 500系はUI表示方針も決める
Next.jsならerror boundaryでラップして共通ハンドリング可能

✅ REST設計の詰まりポイント

ネストリソース (/users/:id/posts) → 実案件では多い
Optional Query (/users?isActive=true) → クエリ生成関数を作成推奨
Pagination / Cursor → 無限スクロール時に詰まりやすい

2. GraphQL編

✅ RESTと違う事前設計の重要性

クエリ依存でオーバーフェッチ / アンダーフェッチが起きやすい
スキーマ変更時に全クライアント影響注意
Apollo ClientやRelay導入の適切さを見極める

✅ クライアントコード生成（自動化）

graphql-code-generatorを実務で導入すると型定義自動化可能
スキーマ駆動開発に向いている

例

yarn add @graphql-codegen/cli
npx graphql-codegen init

✅ キャッシュ戦略の設計

Apolloの cache-first / network-only 切替重要
SSRとの整合性で詰まりがち（特にNext.js App Router併用時）

3. 共通詰まりポイント

✅ OpenAPI連携で型安全化

API定義からTS型自動生成することで手戻り削減
openapi-typescript-codegen など利用実績多い

✅ 認証フローの罠

OAuth2のリフレッシュトークン設計忘れ
CookieベースセッションでのCORS設定漏れ
CSRF対策：SameSite属性とToken送信のバランス

✅ APIバージョン設計

/v1/ のルーティングをAPI側で固定管理
将来的な互換性維持のために意識必須

4. React Query / SWRの活用Tips

✅ 非同期キャッシュの適切な使い分け

const { data, isLoading, error } = useQuery(['user', id], () => api<User>(`/api/users/${id}`));

queryKeyの粒度設計が超重要（キャッシュ汚染防止）
staleTime と cacheTime を意識
再フェッチタイミングのUX考慮（タブ復帰・フォーカス復帰時など）

まとめ

REST/GraphQL問わず、「型安全・エラーハンドリング・キャッシュ設計」 が実務成否を分ける
認証/CORS/CSRFは案件でトラブル頻度高め→事前に潰しておく
API連携は実案件で経験を積むと大きな武器になる

おわりに

API連携は「一通り学んだ」あとに、実務で詰まるポイントが本番です。逆に、ここを乗り越えたエンジニアはフロントエンドでも提案・設計・保守に強くなれます。

Qiitaでは今後もこういった実務に役立つAPI連携Tipsを発信していくので、ぜひLGTM・フォローお願いします！