POSTだけを使っているの？EchoAPIがもっと良い方法を知っています

多くの開発チームでは、POSTかPUTを使うかを決めることが、私たちが愛称で呼ぶ**「ドキュメントレベルの戦争」**を引き起こすことがあります。激しいSlackのスレッド、長々としたNotionのコメント、たまに見せる受動的なイライラを表す絵文字のリアクション。皆が自分の好みを持っていて、誰もが意見が一致しません。

でも、一度は実際に考えてみたことがありますか？これらのHTTPメソッドはどこから来たのですか？ なぜこんなにたくさんあるのですか？それらはどんな問題を解決するために発明されたのですか？そして、もっと重要なのは、EchoAPIがこの何十年も前のジレンマに新しい解決策をもたらす方法とは？

昔はGETとPOSTだけだった時代

インターネットの初期——ダイヤルアップの音やテーブルベースのレイアウトを思い出すと——インターネットはわりとのんびりとした場所でした。必要なのは2つのHTTP動詞だけでした：

• GET：モノを取ってくる
• POST：モノを送る

それだけあれば十分でした。ウェブサイトはただのドキュメントで、一番インタラクティブなことはコンタクトフォームを送信することでした。API？ほとんどの人はその言葉を聞いたこともありませんでした。

でもインターネットは成長しました。Web 2.0、REST API、モバイルアプリが登場しました。今では、ウェブサイトはモノを表示するだけではなく、モノを操作する必要がありました。人々はプロフィールを更新したり、コメントを削除したり、設定を変更したり、システムのステータスを問い合わせたりするようになりました。GETとPOSTの二択の世界ではもう足りないようになりました。

そこで、この増大する複雑さを整理するために、新しいHTTPメソッドが導入されました：

• PUT：リソース全体を置き換える（例えば、製品オブジェクト全体をアップロードする）
• PATCH：フィールド1つに正確な変更を加える（全体のペイロードを送信せずに）
• DELETE：POSTで偽の削除を行うのをやめる
• HEAD：リソースが存在するかどうかだけチェックする（ありがとう）
• OPTIONS：サーバーのドアをノックするようなもの——「これできますか？」と聞く

これらのメソッドはRFC 7231で標準化され、私たちがAPIの意図を説明するための語彙を形づけるようになりました。

これらの動詞はただコードを整理するだけではなく、私たちのAPIをより表現力豊かで、自己記述的で、自動化しやすいものにしました。つまり、より良いドキュメント、賢いツール、チーム間の誤解が少なくなるということです。

しかし、実際のAPIは汚い

でも、正直言ってください——その整然とした構造にもかかわらず、実際のAPIで働く人なら誰でも知っていること：標準のHTTPメソッドはしばしば役に立たないことがあります。

• ファイルを別のフォルダに複製する必要がある？ あなたはPOST /fileと謎のボディ{ "action": "copy", "target": "/new-folder" }を使ってそれを偽造するしかありません。
• ドキュメントをロックして競合する編集を防ぎたい？ それはおそらく/doc/lockという名前の別のPOSTです。
• サードパーティのサービスとデータを同期させようとしている？ 今度はPOST /syncかPOST /jobを使って{ "type": "sync", "retry": true }を発明するはめになります。チームの誰もがそれを differently 読み取ります。
• プロダクションで古いキャッシュをクリアする？ 誰かがPOST /cache?action=purgeを書きます。それは機能します——誰かがactionパラメーターを忘れると何も起こらないまでです。
• リソースのメタデータだけを取得する必要がある？ おめでとうございます、あなたは今GET /resource/metaを構築しました。

もちろん、これらはすべて「機能します」。でも、それはduct tape（応急処置）です。
あなたは動詞を偽造しています。エンドポイントをオーバーロードしています。説明書を書いて、自己明か应该是なことを説明するために使っています。
さらに悪いことに、チームのメンバーそれぞれがそれを少し differently 取り扱うかもしれません——それは不一致の論理、セキュリティの頭痛、テストの混乱を引き起こします。

これはただの悪いスタイルではありません——それは隠れた技術的負債です。
そして、あなたのシステムが大きくなるほど、それはますます痛くなります。

💡 EchoAPI：現代のエレガントさ

EchoAPIでは、私たちは考えました：HTTPと戦うのではなく、受け入れる方法はないでしょうか？

私たちは、これらのあまり使われていないが非常に便利なHTTPメソッドのネイティブサポートを構築しました：

しかし、そこで止まりませんでした。

私たちはまた、あなたが自分のHTTPメソッドを定義することを許可しました。

だから、あなたのシステムにPOST + type=syncDataやPOST + action=exportがある場合、それを次のようにレベルアップすることができます：

• SYNC
• EXPORT
• REINDEX
• ARCHIVE

突然、あなたのAPIはまるで本物の言語のように読めるようになります——きれいに、表現力豊かで、ジュニア開発者や外部のインテグレーターにとっても明らかです。

なぜそれが重要なのか（あなたが思っている以上に）

• より明確なAPIドキュメント：「これはPOSTですが、実際には何かを削除します」というような注釈を書く必要がありません。
• より良いコラボレーション：フロントエンド、バックエンド、QA、PMたちはすべてメソッドベースの同じ言語を話します。
• より賢いテスト：ツールは、ただのパスではなく意図に基づいてテストを自動生成することができます。
• よりきれいなモックデータ：テストシナリオに合うためにメソッドを偽造する必要がありません。

そして、もっとも重要なのは、あなたのAPIがデモするのに誇りを持てるものになることです。

RFC 7231は私たちに語彙を与えました。
EchoAPIはそれを用いてより良い物語を語ることを助けてくれます。

実際のビジネスロジック向けの戦略

EchoAPIは、IETFのドキュメントで定義されたすべてのマイナーなメソッドをサポートするためのものではありません。EchoAPIは——最高の意味で——意見を持っています。私たちは、次の条件を満たすHTTPメソッドに焦点を当てます：

• ビジネスワークフローで頻繁に使われる
• システムの動作において敏感である
• 伝統的なREST設計において曖昧である

私たちの目標は？開発チームが意味論を議論するのをやめ、クリーンで保守しやすいAPIをリリースし始めるのを助けることです。

「あなたのAPIの動作がその意味と一致するようにしてください。」

だから、そのまま進んでください——その恥ずかしい POST + action=magicを廃止してください。
独自のメソッドを定義してください。
あなたのAPIがついに何をしているかのように話すことができるようになります。