API設計

（えーぴーあいせっけい／API Design）

起点・背景（海外）
2000年
更新
2026-09-24

一言でいうと

システム同士が機能やデータをやり取りするときの取り決めを、実装の前に設計する作業です。

開発元と登場年

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の種類を明記してください。候補者は自分の経験との距離を判断しやすくなります

出典