商品検索結果リソースのJSON表現を考えた

商品リソースに引き続き、商品検索結果リソースのJSON表現についても考えてみました。

まず、linkプロパティで「自分自身のURI」「前後ページのURI」「最初と最後のページのURI」を示すことにします。

続いて、totalResults、startIndex、itemsPerPage、Queryの各プロパティで、「商品数」「表示開始位置」「ページごとの商品表示数」「検索キーワード」を示すことにします。camelCaseにしたのは、これらのプロパティ名がOpenSearch由来だからです。それに引き換え、hProductの各フィールド名は「hyphen-separated-lowercase-words」で書くことになっています。

最後に、itemsプロパティで「該当商品リスト」を示すことにします。itemsというぐらいなので配列です。個々の商品の表現は、前回の商品リソースと同様とします。

結果、できたのが下記のJSON表現例です。itemsの中身をすべて記すと煩雑になるので、最初の商品以外は省略しています。

迷った点

リンク先のリソースが複数のフォーマット（ここではHTMLとJSON）で表現できる場合に、どちらにリンクすべきなのか、あるいはプラトニックな（フォーマット独立の）URIにリンクすべきなのか、しばらく迷いました。

linkプロパティについては、今のところ、どちらのフォーマットにもリンクさせています。プラトニックなURIにリンクさせて「300 Multiple Choices」を返す手もありますが、クライアントの立場に立つと処理が煩雑になる（したがってURIを組み立てたい誘惑にかられる）気がしたためです。

hProductのurlフィールドについては、複数のURIは指定できないため、HTML表現へのリンクにするか、JSON表現へのリンクにするか、プラトニックURIへのリンクにするかの三者択一となります。前掲の理由でプラトニックURIは却下、またJSONからHTMLにリンクするのもおかしな気がしたので、JSON表現へのリンクを選びました。