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設計との違い |
|---|---|---|
| REST | Fieldingが示したアーキテクチャのスタイル | 設計の考え方のひとつ。API設計はRESTを選ぶかどうかを含めて決める |
| OpenAPI Specification | HTTP APIを記述する仕様 | 設計の結果を書き表す形式 |
| GraphQL | 取得するデータの形を呼び出す側が指定できる問い合わせ言語 | 設計の形式の選択肢のひとつ |
| ソフトウェアアーキテクチャ | システム全体の構成要素とその関係 | 対象の範囲が広い。API設計は構成要素の間の取り決めに絞った設計 |
採用担当の見極めポイント
- 「APIを作った」という経験が、決められた仕様どおりに実装したものか、仕様そのものを決めたものかを分けて聞いてください。質問の例は「仕様の決定、実装、公開後の運用のうち、どこを担当しましたか」です
- 既存の利用者がいるAPIを変更した経験を聞き、互換性をどう保ったかを確認してください。版の分け方、非推奨にしてから廃止するまでの期間、告知の方法を具体的に答えられる場合は、運用まで担ってきたと判断する材料になります。前職の仕様書の中身ではなく、判断の理由を聞きます
- 求人票では、社内向けか外部向けか、RESTかGraphQLかなど、扱うAPIの種類を明記してください。候補者は自分の経験との距離を判断しやすくなります
設計の判断は、観点ごとに分けて確認します。
| 観点 | 面接での質問の例 |
|---|---|
| リソースと操作の単位 | 「標準の操作に収まらない処理をどう扱いましたか」 |
| エラーの返し方 | 「エラーの理由をプログラムで判別できる形でどう返しましたか」 |
| バージョン管理と互換性 | 「互換性を壊す変更かを、リリース前にどう判定しましたか」 |
| 認証 | 「認証方式をどう選び、許可する操作をどう絞りましたか」 |
出典
- Architectural Styles and the Design of Network-based Software Architectures(Roy Thomas Fielding、カリフォルニア大学アーバイン校 博士論文、2000年。RESTの出典)
- OpenAPI Specification v3.2.1(OpenAPI Initiative。HTTP APIを記述する仕様)
- API design guide(Google Cloud Documentation。2014年から社内で使われているAPI設計ガイド)
- AIP-121: Resource-oriented design
- AIP-193: Errors
- AIP-180: Backwards compatibility
- AIP-185: API Versioning