日向夏特殊応援部隊

俺様向けメモ

PATCH メソッド、新しい HTTP Status Code

Spec はあまりミーハーに追いかけても後で痛い目にあったりするもんですが、久しぶりに面白いなーと思ったのでちょっと取り上げてみます。
ちなみに斜め読みなので記事の正確性についてはあまり保証しませんw

PATCH Method for HTTP

RFC 5789 にある PATCH Method for HTTP ですが、RESTful API の致命的な弱点でもある PUT がリソースの完全なる置き換えなのに対して、PATCH は差分適用である所が中々面白いです。

2.1. A Simple PATCH Example のサンプルを見てみます。

PATCH /file.txt HTTP/1.1
Host: www.example.com
Content-Type: application/example
If-Match: "e0023aa4e"
Content-Length: 100

[description of changes]

Content-Type では元のリソースに対して何らかのパッチ形式を定義して、If-Match ヘッダでは該当するバージョンみたいな物を指定してるんでしょうね。

例えば SQL ならば、

UPDATE resources SET /* description of changes */ WHERE id = 'file.txt' AND version = 'e0023aa4e';

みたいなニュアンスなんでしょうね。3.1 The Accept-Patch Header で OPTIONS メソッドとして受け入れられる PATCH メソッドの本文形式を照会出来ると、まぁ良く出来てますねーって印象です。

OpenSocial の RESTful API だと、9.3 Partial Updates でなんとなーく規定されているように、

GET /appdata/@me/@self/@app

200 OK
Content-Type: application/json; charset=utf-8
ETag: "akb1"

{
 "pokes" : 3,
 "last_poke" : "2008-02-13T18:30:02Z"
}   

みたいなエントリがあったとして、

PUT /appdata/@me/@self/@app?fields=pokes
Content-Type: application/json; charset=utf-8
If-Match: "akb1"

{
  "pokes": 4
}

とかが Partial Updates ですね。そういう訳で PUT メソッドと fields パラメータにより結構強引に差分更新を表現していた所が、より明確な意味での実現が提供されてるって感じです。

Additional HTTP Status Codes

Additional HTTP Status Codes draft-nottingham-http-new-status-04 で定義されている幾つかの HTTP Status Code は少なすぎるレスポンスコードの言葉足らずな所を補う意味で良いんじゃないかなーと思ってます。
まだドラフトなんでアレですけど、今後期待したいなと。

3. 428 Precondition Required

3. 428 Precondition Required はさっきの PATCH メソッドによるリクエストの際に、If-Match によるバージョン指定をクライアントに要求とかそういう事が出来るっぽぃですね。

4. 429 Too Many Requests

429 Too Many Requests は現実的に使いたいシーンはあるだろうなーと。
今、こういうのを表現する際に、10.5.4 503 Service Unavailable を使ったりしてたんだけど、予めリクエスト数の上限についてガイドラインを提示しているのであれば、これはクライアント側の問題に帰着させるのが正しいと思うので4xxで表現するのが妥当だよなーなんて思う次第であります。