API設計

(えーぴーあいせっけい/API Design)

起点・背景(海外)
2000年
更新
2026-11-03

一言でいうと

システム同士が機能やデータをやり取りするときの取り決めを、実装の前に設計する作業です。どの操作を用意するか、データの形、エラーの伝え方、既存の利用者を壊さない変え方を決定します。

設計担当の求人票には、操作の単位やエラーの返し方、互換性に関する取り決めのうち、どこまで判断を任せるか記載します。

開発元と登場年

API設計には単一の提唱者はいません。現在のWeb APIの設計で広く参照される考え方のひとつであるRESTは、2000年にRoy Thomas Fieldingがカリフォルニア大学アーバイン校に提出した博士論文「Architectural Styles and the Design of Network-based Software Architectures」で示されました。

その後、HTTP APIの仕様を機械で読める形で記述するOpenAPI Specificationが整備されました。2026年9月時点の最新版は3.2.1です。Googleも、2014年から社内で使ってきたAPIの設計ガイドを一般に公開しています。

何を解決するために生まれたか

システムの機能を外部に開くと、呼び出す側はその取り決めに合わせてプログラムを書きます。取り決めが場当たり的だと、呼び出す側ごとに解釈が分かれ、提供する側が中身を直すたびに利用者のプログラムが壊れます。

API設計では、どの単位で操作を提供するか、入力と出力の形式、エラーの返し方、認証の方法、後から項目を増やしたときに既存の利用者を壊さない方法を、実装より先に決定します。取り決めを文書にしておくと、提供する側と呼び出す側が並行して開発を進められます。

どこで使われているか

Webサービスのバックエンドとフロントエンド、モバイルアプリとサーバー、社内のマイクロサービス同士、外部の企業に機能を提供する公開APIのいずれにも関わります。

設計の形式には、リソースをURLで表してHTTPの操作で扱うRESTのほか、GraphQLやgRPCなどがあります。

人材市場の実情

APIの実装経験を持つバックエンドエンジニアは多い一方で、設計の判断を担った経験を持つ人は限られます。とくに、外部の企業が使う公開APIの設計や、利用者を壊さずに版を上げた経験は、機能を追加する経験とは別に確かめる必要があります。

RESTの作法は独学の範囲でも身につくため、学習の入口は広い部類に入ります。難しさは、利用者が増えたあとの互換性の維持にあります。

混同されやすい技術との違い

用語指すものAPI設計との違い
RESTFieldingが示したアーキテクチャのスタイル設計の考え方のひとつ。API設計はRESTを選ぶかどうかを含めて決める
OpenAPI SpecificationHTTP APIを記述する仕様設計の結果を書き表す形式
GraphQL取得するデータの形を呼び出す側が指定できる問い合わせ言語設計の形式の選択肢のひとつ
ソフトウェアアーキテクチャシステム全体の構成要素とその関係対象の範囲が広い。API設計は構成要素の間の取り決めに絞った設計

採用担当の見極めポイント

  • 「APIを作った」という経験が、決められた仕様どおりに実装したものか、仕様そのものを決めたものかを分けて聞いてください。質問の例は「仕様の決定、実装、公開後の運用のうち、どこを担当しましたか」です
  • 既存の利用者がいるAPIを変更した経験を聞き、互換性をどう保ったかを確認してください。版の分け方、非推奨にしてから廃止するまでの期間、告知の方法を具体的に答えられる場合は、運用まで担ってきたと判断する材料になります。前職の仕様書の中身ではなく、判断の理由を聞きます
  • 求人票では、社内向けか外部向けか、RESTかGraphQLかなど、扱うAPIの種類を明記してください。候補者は自分の経験との距離を判断しやすくなります

設計の判断は、観点ごとに分けて確認します。

観点面接での質問の例
リソースと操作の単位「標準の操作に収まらない処理をどう扱いましたか」
エラーの返し方「エラーの理由をプログラムで判別できる形でどう返しましたか」
バージョン管理と互換性「互換性を壊す変更かを、リリース前にどう判定しましたか」
認証「認証方式をどう選び、許可する操作をどう絞りましたか」

出典