ForHosting KIT · サイト取得・監視

HTTPメソッドの安全性と冪等性を確認

Q: 小文字のメソッド名も使用できますか？

はい。 前後の空白を取り除き、入力名を大文字に正規化してから分類します。

メソッドを再送しても問題ないかが分かります。空白付きで入力した put は PUT と読まれ、安全ではないものの冪等なので、2回送っても1回送ったときと同じ意図した効果になります。ブラウザで無料で使えます。

無料
ブラウザで動作
登録不要
データは端末の外に出ません

無料で実行 API仕様を見る

ご利用方法ウェブAPIメールTelegramアプリ近日

未知の名前には拡張メソッドの性質を推測せず、入力エラーとして明確に応答します。

安全と冪等は別の約束です

安全なメソッドは、情報の取得やサーバーが提供するオプションの確認に使うもので、サーバー上の何かを変えるためのものではありません。HEAD、OPTIONS、TRACEがこの仲間で、安全なメソッドはすべて冪等でもあります。冪等はより広い約束で、同じ内容を何度送っても、1回送ったときと同じ意図した効果になることを意味します。PUTとDELETEは安全ではありませんが、同じ内容を再び保存したり同じものを再び削除したりしても新しい効果は生じないため、冪等です。

再送を有効にする前に確認する

接続が切れ、サーバーがメッセージを受け取ったか分からないときに、この問いが重要になります。メソッドの自動再送を有効にする前にここで確認すると、大文字にそろえたメソッド名、安全かどうか、冪等かどうか、それらをまとめた短い区分が得られます。よくある誤りは、冪等を無害と考えることです。DELETEはデータを変えますが、2回変えることはありません。未知の名前や独自の名前は推測せずに拒否されます。

活用例

再試行ミドルウェアを確認

判定が不確かな通信障害の後に自動再試行を有効化する前に、設定されたメソッドを確認します。

よくある質問

2回目の応答状態が違う可能性があるのに、DELETEが冪等なのはなぜですか？

冪等性が対象とするのはサーバーへの意図した効果であり、応答の一致ではありません。削除を繰り返しても、目指すリソースの最終状態は同じです。

小文字のメソッド名も使用できますか？

はい。前後の空白を取り除き、入力名を大文字に正規化してから分類します。

WebDAVや独自メソッドはどう扱われますか？

未知の名前として拒否されます。性質を判断するには、そのメソッドを定義する仕様またはアプリケーション契約を参照してください。

安全と冪等はどう違いますか？

安全なメソッドは情報を取得するだけで、サーバーに変更を求めません。冪等なメソッドは変更を伴うことがありますが、2回送っても1回と同じ意図した効果になります。PUTとDELETEは安全ではありませんが冪等です。

どのメソッドを判定できますか？

Webの基本仕様とPATCHの仕様で定められた9つの標準メソッドで、PUT、PATCH、DELETE、HEAD、OPTIONS、TRACEなどです。大文字と小文字の違いや前後の空白は無視されるため、put は PUT と読まれます。

開発者向け — APIアクセス

このページの機能はすべてAPIからも利用できます。自社システムに組み込みたいチーム向けのセクションです。それ以外の方は上のツールをそのままお使いください。

エンドポイント

POSThttps://api.kit.forhosting.com/dev2/http-method-idempotent-check

Bearerトークンで認証し、POST1回でタスクをキューに登録します。結果はWebhookまたは署名付きリンクで受け取れます。

お使いのスタックから呼び出す

curl -X POST https://api.kit.forhosting.com/dev2/http-method-idempotent-check \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"PUT"}'

const res = await fetch("https://api.kit.forhosting.com/dev2/http-method-idempotent-check", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "method": "PUT"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev2/http-method-idempotent-check",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "method": "PUT"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev2/http-method-idempotent-check", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"method":"PUT"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"method":"PUT"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev2/http-method-idempotent-check", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

リクエスト例

{
  "method": "PUT"
}

レスポンス例

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "dev2.http_method_idempotent_check",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

非同期APIです。task_idは即時に返ります。ポーリングは1秒あたり1リクエストまでです。

料金

1リクエストあたり$0.002

単価はすべて公開しています。トークン換算や独自クレジットはありません。失敗したタスクは課金されません。

エラー

HTTP	コード	意味
`401`	`unauthorized`	APIキーが無効か、指定されていません。Authorizationヘッダーを確認してください。
`402`	`insufficient_balance`	残高が不足しています。チャージ後に再度お試しください。
`404`	`unknown_type`	指定されたタスクタイプは存在しません。タイプ名を確認してください。
`429`	`rate_limited`	リクエストが多すぎます。しばらく待ってから再度お試しください。

技術的な注記

標準HTTPメソッドを、HTTPセマンティクスで定義された安全性と冪等性によって分類します。GET、POST、PUT、PATCH、DELETEなどを入力すると、正規化したメソッド名、個別の真偽値、簡潔な総合分類を返します。主要なHTTPセマンティクス仕様とPATCH仕様で定義された9種類を判定し、前後の空白や大文字・小文字の違いは吸収します。

安全性と冪等性を区別します

安全性と冪等性は、それぞれ異なる保証を表します。安全なメソッドは、オリジンサーバーの状態変更を要求するためではなく、情報の取得や通信オプションの確認を目的とします。PUTとDELETEは安全ではありませんが冪等です。同じ表現で繰り返し置換したり、同じリソースの削除を繰り返し要求したりしても、実行ごとに別の意図した効果が加わるわけではないためです。GET、HEAD、OPTIONS、TRACEが該当します。HTTPセマンティクスでは、安全なメソッドはすべて冪等とも定められているため、これらの分類は`safe_and_idempotent`です。冪等性の範囲はさらに広く、同一のリクエストを複数回送った場合の意図したサーバーへの効果が、1回だけ送った場合と同じであることを意味します。結果では`safe`と`idempotent`を分けて返すので、ポリシーコードがラベルから一方を推測する必要はありません。表示、記録、単純な分岐には`classification`も利用できます。これらは標準化されたリクエストの意味を示すもので、個別実装に不具合や付随的な副作用がないことまで保証するものではありません。

再試行の意味を正しく判断します

たとえば、最初のDELETEではリソースが削除されて成功を返し、同一内容の次のDELETEでは対象がすでに存在しないと返す場合があります。それでも意図した最終状態は同じです。同じ対象と表現を使う限り、PUTにも同じ性質があります。冪等性は、接続障害の後に自動クライアントがリクエストを再試行してよいか判断するときに特に役立ちます。クライアント側では、最初のリクエストをサーバーが受信したか分からない場合があります。冪等なメソッドを繰り返せば、リクエストが意図した効果は維持されます。ただし、同じステータスコードや同一のレスポンス本文が返る保証ではありません。POSTとPATCHは、一般的な定義では安全でも冪等でもありません。特定のAPIが冪等性キーや条件付きリクエストを採用し、POSTまたはPATCHを再試行可能に設計することはありますが、そのアプリケーション固有の契約によってメソッド自体の標準的な既定値が変わるわけではありません。この結果をプロトコル上の基準とし、利用するAPIが明示した追加保証をその上に適用してください。

ポリシー適用前に名前を検証します

名前だけから拡張メソッドの性質を推測すると、安全でない再試行を許可したり、正当な処理を拒否したりするおそれがあります。システムで拡張メソッドを使う場合は、登録または定義を行った仕様を確認し、明示的なポリシーで扱ってください。このチェッカーが受け付ける標準名は、CONNECT、DELETE、GET、HEAD、OPTIONS、PATCH、POST、PUT、TRACEです。入力の前後にある空白を除去して大文字に変換するため、` get `や`patch`も意味を変えずに正規化されます。それ以外は`invalid_input`エラーになります。HTTPのメソッドトークンは拡張可能なので、この厳密な動作が重要です。WebDAVなどのプロトコルは追加メソッドを定義でき、非公開APIも独自トークンを導入できます。このアルゴリズムはネットワークリクエストを行わず、実際のサーバー、ルート、キャッシュ、プロキシ、リクエスト本文も参照しません。決定的に動作するため、リンター、API文書の検査、再試行ミドルウェアの設定、ブラウザー教材に適しています。ブラウザー版とAPIハンドラーは同じロジックを共有し、APIリクエストには公開基本料金$0.002が適用されます。

連携の活用例

API文書を検査

各エンドポイントのメソッドと、処理が安全または冪等だとする文書の記述を照合します。

HTTPセマンティクスを学習

一般的なメソッドの安全性と冪等性を、決定的な1回の判定で個別に表示します。

技術的な質問

安全なメソッドはすべて冪等ですか？

はい。HTTPセマンティクスでは安全なメソッドを冪等と定義するため、GET、HEAD、OPTIONS、TRACEは両方の性質を備えます。

PATCHは冪等ですか？

既定では冪等ではありません。特定のAPIが再試行可能なPATCH処理を定義する場合はありますが、それはアプリケーション固有の保証です。

KITの完全なドキュメントを見る →