【初心者わかりやすく】REST APIとは？HTTPのしくみとcurlでの試し方

クラウドの管理や機器の自動化を調べていると、「REST API」という言葉をよく見かけます。Microsoft 365 や Azure も、管理用の REST API を公開していて、画面で行う操作の多くをプログラムから行えます。

この記事では、REST API を初めて触る人向けに、REST という名前の意味から、リクエストとレスポンスの読み方までを図で説明します。後半では、インターネットに公開されている API に curl でリクエストを送り、実際の応答を自分の目で確かめます。

API とは

API（Application Programming Interface）は、ソフトウェアが外部のプログラムに向けて用意した窓口です。人はブラウザの画面を見てボタンを押しますが、プログラムは画面を読めません。そこで、決まった形式で依頼を送り、決まった形式で結果を受け取れるようにしたものが API です。

画面からの操作も API からの操作も、最終的にはサーバの同じデータを扱います。違うのは入口です。API を使うと、何十台分の設定確認や毎月のアカウント棚卸しのような繰り返し作業を、スクリプトに任せられます。

REST API とは

REST は「Representational State Transfer」の頭文字をとった言葉です。HTTP/1.0 の仕様の共同執筆者で、HTTP/1.1 の中心的な設計者でもある Roy Fielding が、Web がうまく動いている理由を設計の考え方として整理し、2000年の博士論文で REST と名付けました。特定のプロトコルや製品の名前ではなく、「こういう約束で作るとうまくいく」という設計のスタイルを指します。

「REST」という名前の意味

3つの英単語に分けると、意味がつかみやすくなります。

単語	意味
State（状態）	サーバにあるリソースの、その時点の中身です。たとえば Microsoft Graph なら、「あるユーザーの表示名や部署が、いまどうなっているか」が状態にあたります。
Representational（表現の）	状態を、相手が読める形にしたものが「表現」です。サーバの中のデータそのものを渡すのではなく、JSON のような文字の形に置き換えて渡します。同じリソースでも、JSON や HTML など、違う表現で返すことができます。
Transfer（転送）	表現を HTTP のリクエストやレスポンスに入れて、クライアントとサーバの間で送ります。

つなげると「リソースの状態を、表現にして転送する」という意味になります。Fielding 自身は、Web ページのリンクを選ぶと次のページ（アプリケーションの次の状態を表したもの）が送られてくる、という Web の動きを思い浮かべてもらうための名前だと説明しています。ブラウザで Web ページを見るときと同じしくみを、プログラム同士のやり取りに使うのが REST API だと考えると、イメージしやすいと思います。

REST API の4つの考え方

実務で REST API と呼ばれているのは、おおむね次の4つの考え方に沿った Web API です。

1つ目は、リソースを URL で表すことです。操作したい対象（パッケージのタグ、ユーザーのプロフィールなど）を「リソース」と呼び、それぞれに URL を割り当てます。URL を見れば、何を操作しようとしているかが分かります。

2つ目は、操作を HTTP メソッドで表すことです。「取得」「置き換え」「削除」といった操作の種類は、URL ではなく HTTP のメソッド（GET、PUT、DELETE など）で伝えます。同じ URL でも、メソッドを変えると操作が変わります。

3つ目は、サーバが前のやり取りを覚えないこと（ステートレス）です。サーバは「さっき誰からどんな依頼があったか」を覚えておかず、届いたリクエストの中身だけで処理します。そのため、クライアントは毎回、認証情報も含めて処理に必要な情報をすべて付けて送ります。手間は増えますが、サーバ側は1件ずつ独立に処理できるので、台数を増やして負荷を分けやすくなります。

4つ目は、データを「表現」でやり取りすることです。名前の意味のところで説明したとおり、サーバの中のデータそのものではなく、JSON などの形にしたものを受け渡します。

リソースと URL

REST API では、リソースごとに URL が決まっています。Microsoft 365 や Entra ID のデータを扱う Microsoft Graph を例にすると、「自分のプロフィール」は次の URL で表されます。

リソースを表すのはパスの部分です。/v1.0 は API のバージョンで、その後ろの me が「サインインしている自分」というリソースです。/v1.0/users にすると、ユーザーの一覧という別のリソースになります。

HTTP メソッド：何をしたいか

同じリソースに対して「見る」「作る」「書き換える」「消す」を区別するのが HTTP メソッドです。よく使うのは次の5つです。

メソッド	主な用途	安全	べき等
GET	リソースを取得する	○	○
POST	送ったデータをサーバに処理させる。新しいリソースの作成によく使う	×	×
PUT	送った内容でリソースを作成する、または丸ごと置き換える	×	○
PATCH	リソースの一部を変更する	×	×（作り方によってはべき等にできる）
DELETE	リソースを削除する	×	○

「安全」は、サーバの状態を変えないという意味です。「べき等」は、同じリクエストを何回送っても、1回送ったときと同じ結果になるという意味です。たとえば通信が途中で切れて応答が分からなかったとき、べき等な PUT や DELETE は送り直しても結果が変わりません。べき等でない POST を送り直すと、同じデータが2件できることがあります。

実際の API では、URL とメソッドをどう組み合わせているかを見てみます。Microsoft Graph でユーザーを操作するときは、次のようになっています。URL は /v1.0/users（一覧）と /v1.0/users/{id}（1人）の2種類だけで、何をするかはメソッドで決まります。変更には、一部だけを書き換える PATCH が使われています。

ステータスコード：結果はどうだったか

サーバは応答の先頭に3桁のステータスコードを付けます。1桁目で結果の種類が分かるので、まずここを見ます。

コード	意味
1xx	情報。リクエストを受け取り、処理を続けている
2xx	成功
3xx	リダイレクト。完了には別の操作（別の URL へのアクセスなど）が必要
4xx	クライアントエラー。リクエストの側に問題がある
5xx	サーバエラー。正しそうなリクエストを、サーバが処理できなかった

REST API でよく見るコードは次のとおりです。

コード	意味
200 OK	成功した
201 Created	成功し、新しいリソースができた
204 No Content	成功した。応答で返す中身はない
400 Bad Request	リクエストの形がおかしいなどの理由で処理できない
401 Unauthorized	有効な認証情報が付いていない
403 Forbidden	リクエストは理解したが、実行を拒否した（権限不足など）
404 Not Found	URL の指すリソースが見つからない
429 Too Many Requests	短い時間にリクエストを送りすぎた（レート制限）
500 Internal Server Error	サーバの中で想定外の問題が起きた
503 Service Unavailable	過負荷や保守のため、一時的に処理できない

ヘッダとボディ、JSON

リクエストもレスポンスも、ヘッダとボディに分かれます。ヘッダには、ボディの形式（Content-Type）や認証情報（Authorization）などの付帯情報が入ります。ボディは中身そのもので、REST API では JSON がよく使われます。

JSON（JavaScript Object Notation）は RFC 8259 で決められたテキスト形式です。{ } で囲んだ「名前と値」の組（オブジェクト）と、[ ] で囲んだ値の並び（配列）を組み合わせて書きます。値には文字列、数値、true／false、null も使えます。ボディが JSON のときは、ヘッダの Content-Type が application/json になります。

認証：誰からのリクエストか

誰でも読める公開 API を除けば、多くの API は「誰が送ってきたか」を確かめます。REST はステートレスなので、ログインした状態をサーバに覚えさせるのではなく、リクエストのたびに認証情報を付けて送ります。

よく使われるのは、あらかじめ取得したアクセストークンや API キーをヘッダに入れる方法です。OAuth 2.0 のアクセストークンなら、RFC 6750 の形で Authorization: Bearer <トークン> と書きます。Microsoft Graph や Azure の REST API も、Microsoft Entra ID からトークンを取得し、この形で付けて呼び出します。

curl で公開 API を呼んでみる

ここからは、インターネットに公開されている REST API に curl でリクエストを送り、ここまでの説明を実際の応答で確かめます。curl はコマンドラインから HTTP のリクエストを送れるツールで、Windows にも標準で入っています。

今回使う公開 API：npm レジストリ

題材には、npm レジストリの API を使います。npm は JavaScript の部品（パッケージ）を共有するしくみで、レジストリはそのパッケージと情報をためた公開データベースです。registry.npmjs.org で動いていて、読み取りだけなら登録も認証もいりません。応答も短いので、REST API の動きを確かめるのにちょうどよい題材です。npm を使ったことがなくても、インストールしていなくても試せます。

今回アクセスするのは、express（Web アプリを作るときによく使われるパッケージ）の「配布タグ（dist-tag）」の一覧です。配布タグはバージョン番号に付ける別名で、latest はそのパッケージの現在の版を指すタグで、バージョンを指定せずにインストールすると、このタグの版が入ります。

使うコマンドは、次の部品でできています。

-w の中の %{http_code} はステータスコード、%{content_type} は Content-Type、\n は改行を表します。これを付けておくと、ボディ（JSON）のあとに、結果のステータスコードとボディの形式が1行で表示されます。

以下の出力は、Linux の curl 8.5.0 で、2026年10月に取ったものです。返ってくるバージョン番号は、その後のリリースで変わります。

GET でリソースを取得する

まず、express の配布タグの一覧を GET で取得します。やり取りは次のようになります。

実際のコマンドと出力です。

ターミナル

$ curl -s -w "\n%{http_code} %{content_type}\n" https://registry.npmjs.org/-/package/express/dist-tags
{"latest":"5.2.1","latest-4":"4.22.3"}
200 application/json

1行目がボディ（JSON）、2行目が -w で表示させたステータスコードと Content-Type です。

表示	意味
“latest”:”5.2.1″	latest タグが指しているバージョン（取得した時点）
“latest-4″:”4.22.3”	express が独自に付けているタグで、4.22.3 を指している
200	成功
application/json	ボディが JSON であること

存在しないリソースを指定する

次に、存在しないパッケージ名を指定して GET を送ります。

実際のコマンドと出力です。

ターミナル

$ curl -s -w "\n%{http_code} %{content_type}\n" https://registry.npmjs.org/-/package/hirotanoblog-no-such-package/dist-tags
"Not Found"
404 application/json

404 が返りました。URL の指すリソースがないという意味なので、まずパスの綴りを疑います。ボディの "Not Found" も JSON で、文字列1つだけの JSON です。

認証なしで削除しようとする

最後に、-X DELETE でタグを削除するリクエストを送ります。Authorization ヘッダ（認証情報）は付けていません。

実際のコマンドと出力です。

ターミナル

$ curl -s -X DELETE -w "\n%{http_code} %{content_type}\n" https://registry.npmjs.org/-/package/express/dist-tags/hirotanoblog-test
"Unauthorized"
401 application/json

401 で断られました。タグの追加や削除はパッケージの管理者だけができる操作で、このリクエストには誰が送ったかを示す情報がないためです。401 は「リクエストは適用されていない」という意味なので、レジストリの内容は変わっていません。

似たコードに 403 があります。401 は有効な認証情報がないとき、403 は相手が誰かは分かったうえで実行を拒否したときに返ります。トークンを付けているのに 403 になる場合は、トークンに与えた権限が足りないことを疑います。

実務で出会う REST API

インフラの仕事で触れる機会が多いのは、次のような API です。どれも、URL でリソースを決め、メソッドで操作を伝え、ステータスコードとボディで結果を確かめる、という読み方は同じです。

API	内容
Microsoft Graph	Microsoft 365 や Entra ID のデータを扱う RESTful な API。https://graph.microsoft.com を入口に、ユーザー、メール、Teams などを操作する
Azure Resource Manager の REST API	Azure のリソースを作成・変更・削除する API。Azure portal、Azure CLI、Azure PowerShell からの操作も Resource Manager が受け付けて処理する
RESTCONF（RFC 8040）	YANG で定義されたネットワーク機器の設定や状態を、HTTP で読み書きするための標準プロトコル

うまくいかないときの切り分け

状態	よくある原因	確認すること
401	認証情報を付けていない、トークンの期限切れ、ヘッダの書き間違い	Authorization ヘッダがあるか、Bearer とトークンの間の空白、トークンの有効期限
403	認証はできたが、権限が足りない	アカウントやアプリに与えた権限（ロール、スコープ）
404	URL の誤り、リソースがない、API のバージョン違い	パスの綴り、ID、ドキュメントの URL との違い
405	そのリソースが受け付けないメソッドを使った	ドキュメントのメソッド。応答の Allow ヘッダに使えるメソッドが入っている
415	ボディの形式がサーバの想定と違う	JSON を送るときに Content-Type: application/json を付けたか
429	短い時間に送りすぎた	Retry-After ヘッダがあれば、その時間だけ待ってから送り直す
5xx	サーバ側の問題や一時的な過負荷	時間をおいて再試行する。POST を送り直すときは、二重登録にならないか確かめる

まとめ

用語	ひとことで
REST API	リソースを URL で表し、HTTP のメソッドで操作する Web API
リソース	操作の対象（ユーザー、パッケージ、設定など）
メソッド	GET 取得、POST 処理・作成、PUT 置き換え、PATCH 一部変更、DELETE 削除
ステータスコード	2xx は成功、4xx はリクエスト側の問題、5xx はサーバ側の問題
JSON	{ } と [ ] でデータを表すテキスト形式。Content-Type は application/json
認証	リクエストのたびに、Authorization ヘッダでトークンなどを送る

最初は GET で公開 API の応答を眺め、ステータスコードとボディの組み合わせに慣れておくのがおすすめです。そのうえで Microsoft Graph やネットワーク機器の API のドキュメントを読むと、どの URL にどのメソッドを送ればよいかが追いやすくなります。

Azure のリソース操作の記録（Azure Activity ログ）を Microsoft Sentinel に取り込む手順は、MS SentinelにAzure Activityログを取り込む で紹介しています。