The following two tabs change content below.
アバター画像

メンバー

福岡市博多区でWebシステム開発の受託・ラボ型SES・web集客サービス、３つのWebサービスを提供中

APIの設計判断が“〇〇エンジニア”に求められる理由

「使う側」から「選ぶ側」へ視点が変わるタイミング

キャリア3年目を過ぎると、単にAPIを叩く側ではなく「どう設計し、何を選択すべきか」を考えるシーンが増えてきませんか？

実は、私も設計レビューやアーキテクチャ選定に関わるようになり、RESTとGraphQLのどちらを選ぶべきか迷う場面がありました。

本記事では

・設計の仕方

・使い分け方

・選択の仕方

を、5年以上の実務経験から得た知見をもとに、API設計で重要となる両者の特徴や使い分け方をお伝えします。

この記事を読めば、あなたもAPIの活用上手な中堅エンジニアになれるかもしれません。

中堅エンジニアの設計が開発効率を大きく〇〇する

中堅エンジニアは以下の設計ミスの影響で開発効率が悪くなる、と言われています。

・設計初期でのAPI選定ミス

・クライアントとバックエンド間の認識齟齬

・保守性の低い設計

以上、3つの設計ミスが開発効率を大きく左右しますので、気をつけることをオススメします。

REST APIとGraphQLのざっくりした違い

REST APIとGraphQLは、どちらもWeb APIを設計するための方法や思想ですが、それぞれ異なる特徴を持っています。

どちらを設計を選択するか、まずは違いを抑をえておきましょう。

REST API：HTTPメソッドとエンドポイントによる操作

RESTはリソース単位の操作に適しており、Webの標準的なAPI設計スタイルです。

  • GET /users           → ユーザー一覧
  • GET /users/1         → ユーザー詳細
  • POST /users          → ユーザー作成
  • PUT /users/1         → ユーザー更新
  • DELETE /users/1      → ユーザー削除
  • クライアントがURLとHTTPメソッドを使い分ける
  • キャッシュやツールの対応が強い

参考：RESTful APIの設計原則

GraphQL：必要な情報を自由に取得できるクエリベースの設計

GraphQLは、クライアントが取得するデータ構造を明示的に指定できます。

query {

  user(id: 1) {

    name

    email

    posts {

      title

      createdAt

    }

  }

}
  • 1つのエンドポイント(/graphql)で完結
  • 過不足ないデータ取得が可能

 参考：GraphQL公式サイト

REST APIの具体例と導入経験

それでは実際に私が関わった案件でどのAPIを導入したかを体験を踏まえながらお伝えしていこうと思います。

プロジェクトでの導入背景と運用の実際

申請ワークフローシステム開発（SPA）で、REST APIを採用。

選定理由は：

  • 既存のマイクロサービス群がRESTベースだった
  • フロントエンドがReactで構成されており、RESTとの親和性が高い
  • SwaggerによるAPIドキュメント管理が容易

結果：

  • 一般的なGET / POST / PUT / DELETE操作が明確
  • ただし、クライアント側で複数リクエストが必要な場面が多かった
    （例：ユーザー詳細 + 投稿一覧）

Swaggerのドキュメントについてはこちらを参照してください

GraphQLの具体例と導入経験

柔軟性と開発効率を重視したケーススタディ

ビル管理プラットフォーム（ビルOS）開発においてGraphQLを採用しました。

主に以下のような異種データソースを統合して可視化・操作する必要があったため、GraphQLの柔軟性が非常に有効でした

  • ビル側が持っている混雑度情報（センサー経由）
  • 業務ロボットが走行可能な経路情報（施設マップとの統合）
  • 外部APIから取得するリアルタイムの天候情報

これらを1リクエストで取得できるようにし、フロントエンド側でUI構成に応じた柔軟なデータ取得が可能となる設計を目指しました。

  • 異なるデータソース（混雑度・経路・天候情報など）を一括取得する必要があった
  • それぞれのデータ提供元が異なるため、統合的なデータ取得ができるGraphQLが適していた
query GetBuilding($id: ID!) {

  building(id: $id) {

    name

    location

    facilities {

      type

      status

    }

    tenants {

      name

      contractEnd

    }

  }

}

結果：

  • API設計の自由度が高く、UI変更に強かった
  • Apollo Clientでキャッシュ管理や型安全も担保できた
  • 一方で、スキーマ設計やN+1問題への対応に一定の知識が必要

 参考：Apollo GraphQL

どっちを使うべきか？

どちらを使用すべきかシーン別に紹介していきます。

利用シーン

REST API：Web、シンプルなCRUD中心のアプリ
GraphQL ：動的・複雑なフロントを持つSPAやモバイルアプリ

ドキュメント管理

REST API：Swaggerなどが充実
GraphQL ：GraphQL SDLで自動生成

保守性

REST API：標準的で他チームと連携しやすい
GraphQL ：クエリ依存で管理が分散しやすい

実務での判断ポイント

・API仕様がすでにRESTベース → そのまま使用する方が安全
・クライアントが頻繁にUI変更 → GraphQLが柔軟

実務経験からの気づき・個人の見解

私が実際に現場で設計、導入を行い

  • RESTは汎用性・分かりやすさに優れており、他チームとの連携・拡張時の安全性が高い
  • GraphQLは柔軟で高速なフロント開発を可能にするが、初期設計・運用コストに注意
  • 両者の一番の違いは「誰がデータの構造を決めるか」
    → RESTはサーバー、GraphQLはクライアント

今後は、RESTとGraphQLのハイブリッド構成（RESTで認証、GraphQLでUIデータ取得）が主流になると感じています。

最後に

APIの設計は、開発者の設計思想が色濃く出る領域です。 「RESTかGraphQLか」という二択ではなく、「何を実現したいか」「どのチームがどこまで責任を持つか」を軸に選定すべきです。

中堅エンジニアとしては、どちらにも対応できるスキルを持ち、プロジェクト特性に応じて最適なAPI構成を選べる判断力を身につけていきましょう。

参考リンクまとめ