REST APIとはHTTPメソッドと設計の基本
REST APIとは、HTTPでリソースを操作するWeb APIの設計スタイルです。GET・POST・PUT・DELETEの使い分けと、冪等性、設計時と利用時の注意点を整理します。
公的機関・公式資料などの一次情報と照合して作成しています。このサイトについて
REST APIとは
REST（Representational State Transfer）は、効率的で信頼性が高く、拡張しやすい分散システムを作るための、設計上の制約の集まりです。MDN Web Docs の用語集では、リソース（文書やデータなど）を中心に考え、言語に依存しない標準化されたやり取りを行う考え方だと説明されています。
実務では、REST API という言葉は「HTTPで呼び出せるWeb API」くらいの意味で使われることが多くなっています。MDNも、初心者は標準的なWebのライブラリやツールで呼び出せるHTTPサービスと捉えてよいと述べています。一方で、RESTful と呼ばれるAPIの多くが、RESTのすべての制約には従っていない点にも触れています。つまり、REST API と名乗っていても、設計の厳密さは製品ごとに違います。
基本（仕組み・方法）
RESTでは、操作の対象を URL で表し、操作の種類を HTTP メソッドで表します。
| メソッド | 役割 | 安全 | 冪等 |
|---|---|---|---|
| GET | リソースを取得する | はい | はい |
| POST | データを送って、新しい処理や作成を行う | いいえ | いいえ |
| PUT | リソース全体を置き換える | いいえ | はい |
| PATCH | リソースの一部を変更する | いいえ | いいえ |
| DELETE | リソースを削除する | いいえ | はい |
ここでの安全とは、サーバー側の状態を変えないこと、冪等とは、同じリクエストを何度送っても結果が1回目と同じになることです（MDNの分類による）。たとえば DELETE を同じURLに2回送っても、最終的には「削除された状態」で変わらないので冪等です。一方、POST で注文を作成するAPIを2回呼ぶと、注文が2件できる可能性があります。通信が不安定で再送するときは、この違いが重要になります。
リソースを表す URL の例を示します。
| 目的 | メソッドとURLの例 |
|---|---|
| 顧客の一覧を取得 | GET /customers |
| 顧客1件を取得 | GET /customers/123 |
| 顧客を新規作成 | POST /customers |
| 顧客を更新 | PATCH /customers/123 |
| 顧客を削除 | DELETE /customers/123 |
URLには動詞ではなく名詞を使い、動作はメソッドに任せる形が基本です。
REST APIの具体例
ステータスコードも、REST APIの読み方の要になります。
| コード | 意味 | 利用側の対応 |
|---|---|---|
| 200 | 成功 | 結果を使う |
| 201 | 作成成功 | 返された新しいIDを保存する |
| 400 | リクエストが不正 | 入力値を直す |
| 401 | 認証されていない | キーやトークンを確認する |
| 404 | 見つからない | URLやIDを確認する |
| 429 | リクエストが多すぎる | 間隔をあけて再試行する |
| 500番台 | サーバー側の問題 | 時間をおいて再試行、続くなら問い合わせる |
たとえば、5件ずつ取得するAPIで顧客が1,230件ある場合、ページ送りで 1,230 ÷ 5 = 246 回のリクエストが必要です。1回で最大100件取得できるなら、必要なのは 13 回（1,230 ÷ 100 = 12.3 を切り上げ）です。上限の確認が処理時間やレート制限に直結します。
REST APIの実践ステップ
- 公式ドキュメントで、リソースの一覧と、各URLで使えるメソッドを確認する。
- 認証方式を確認し、読み取り専用の権限で試す。
- GET で1件取得して、レスポンスの形（項目名、型）を把握する。
- 書き込みは、テスト用のデータで POST や PATCH を試す。
- 失敗時の再試行ルールを決める。冪等なメソッドは再送しやすく、POST は二重作成に注意する。
- 一覧取得はページ送りの仕様（件数、次ページの指定方法）に従って実装する。
REST APIの注意点
- 名前が REST でも、実際の仕様は製品ごとに違います。URLの設計、エラーの返し方、ページ送りの方式は、必ず各社のドキュメントに従ってください。
- GET で状態を変える設計は避けるのが原則です。検索エンジンや事前読み込みが勝手にURLを呼ぶことがあり、意図しない変更が起きるおそれがあります。
- POST の再送は、二重作成の原因になります。重複防止の仕組み（固有キーの指定など）があるか、仕様で確認します。
- 認証情報をURLのクエリ文字列に入れると、ログに残りやすくなります。推奨される渡し方があるなら、それに従います。
REST APIでよくあるミス
- PUT と PATCH を同じものと考え、一部の項目だけを PUT して、ほかの項目を空にしてしまう。
- 429 エラーが出ているのに、すぐに再試行を繰り返して状況を悪化させる。
- 一覧の1ページ目だけを取得して、全件だと思い込む。
- 本番のIDとテストのIDを取り違えて、削除する。
REST APIのチェックリスト
- 使いたい操作に対応するURLとメソッドを確認したか。
- 認証の方式と、権限の範囲を理解しているか。
- ページ送りと、1回あたりの取得上限を確認したか。
- エラー時と上限超過時の動きを決めたか。
- 削除や更新は、テスト用データで先に試したか。
REST APIのFAQ（よくある質問）
Q. REST API と Web API は同じですか。
A. 同じではありません。Web API はWeb上で呼び出すAPI全般を指し、REST API はその設計スタイルの1つです。GraphQL など、別の方式もあります。
Q. RESTful の条件は何ですか。
A. 学術的には、RESTの制約すべてに従うことを指します。ただし実務では、緩やかな意味で使われることが多く、製品ごとの仕様確認が必要です。
Q. JSON以外の形式もありますか。
A. あります。XMLなども使われますが、現在のWeb APIではJSONが広く使われています。
筆者の見解（REST API）
REST を厳密に学ぶ価値はありますが、ツールを導入する立場で本当に大切なのは、冪等性と再送の扱いだと考えます。通信は必ず失敗することがあり、そのときに二重処理が起きるかどうかで、自動化の信頼性が決まります。私見では、API仕様を読むときは、機能一覧よりも先にエラーと再送の項目を探すとよいです。
REST APIの関連項目
出典（一次情報）
本記事は一般的な情報の提供を目的としています。SaaS・ツールの機能・料金・無料枠・仕様は頻繁に更新されるため、最新の内容は各社の公式ページでご確認ください。契約・法務・セキュリティに関する判断は、専門家や社内の担当部門にご相談ください。「筆者の見解」は一つの考え方です。