API・開発の基礎用語

API・開発の基礎用語とは｜このカテゴリで分かること

APIとは、ソフトウェア同士が決まった形式でやり取りするための窓口です。SaaSを導入すると「APIで連携できます」「Webhookで通知します」といった言葉が必ず出てきますが、このカテゴリでは、APIとは何かをわかりやすく説明するところから、エンドポイント、REST、OpenAPI、GraphQL、APIゲートウェイまでを、プログラマーでない人にも読める順で整理します。

対象は、SaaSの連携機能を選ぶ担当者、開発者との会話についていきたい企画・営業職、これから開発を学ぶ人です。ゴールは「外部APIをつなぐ話が来たときに、何を確認すればよいか分かる」ところまでです。個々の製品の操作手順は扱わず、用語の関係と判断の観点に絞っています。

はじめにおすすめの3本

迷ったら、まずこの3本から読んでください。残りの記事は、このページ下の項目一覧から、気になるテーマで選べます。

1. APIとは｜仕組み・種類・使うときの注意点
   まずAPIそのものの意味を押さえます。以降の用語はすべてこの上に乗っています。
2. エンドポイントとは｜APIのURL構造と読み方
   「どのURLに何を送るか」という、APIを使う最小の単位です。
3. REST APIとは｜HTTPメソッドと設計の基本
   世の中のWeb APIの多くが前提にしている設計の考え方です。

押さえておきたいポイント（リサーチ）

公式ドキュメントで確認できた事実のうち、判断に直結するものを選びました。

「べき等」は、たとえば通信が途切れて同じリクエストを再送しても結果が変わらない性質のことです。再送の安全性は設計に直結するため、決済や登録のAPIで特に意味を持ちます。なお、OpenAPIの最新版の番号や各社のAPIの仕様は更新されるため、最新は公式で確認してください。

よくある疑問

Q. APIとWebhookは何が違いますか。
A. APIは必要なときにこちらから呼び出して取りに行く方式、Webhookは何かが起きたときに相手から通知が届く方式、と整理できます。詳しくは Webhookとは｜APIとの違いと仕組み・使うときの注意点 を参照してください。

Q. APIキーとOAuthはどちらを使えばよいですか。
A. 自分のシステムが自分の権限で使うならAPIキー、他人のアカウントのデータを本人の同意で扱うならOAuthが基本です。違いと漏えい対策は APIキーとOAuthの違い｜認証方式の選び方と漏えい対策 にまとめています。

Q. RESTとGraphQLはどちらが良いですか。
A. 優劣ではなく、データの取り方の違いです。判断の観点は GraphQLとは｜RESTとの違いと向いている場面 と REST APIとは｜HTTPメソッドと設計の基本 を読み比べると見えてきます。

Q. 外部APIをつなぐと何が問題になりますか。
A. 相手の仕様変更や提供終了、利用回数の上限、キーの漏えいが代表的です。つなぐ前に仕様書と利用条件を確認し、キーの置き場所を決めておくことが前提になります。