HAL + JSONハイパーメディアタイプはRESTのメディアタイプではありませんか？

Question

HAL + JSONハイパーメディアタイプは、RESTfulサービスを作成する方法で使用できますか？

私が読んだところでは、RESTful APIのクライアントは、別のリソースを特別なケースで扱う必要はありません。代わりに、どのようなリソースがどのように見えるかを記述するためにメディアタイプを使用する必要があります。

HAL specは、この例を示します。このサンプルHAL + JSONサービングAPIのクライアントとして

GET /orders 

{ 
    ... 
    "shippedToday": 20, 
    ... 
} 

`` `

、私は「順序」は持っていることを知っておく必要があるように見えますshippedTodayの属性これは、クライアントが表現の構文を理解する必要がないという制約に反しているようです。

これはHALの批判ではありません。問題は、RESTfulなAPI設計について私（および他者）の理解を助けることです。

Answer 1

HAL + JSONハイパーメディアタイプは、RESTfulサービスを作成する方法で使用できますか？

はい、間違いありません。

APIには広告申込情報のURL（/）が必要です。

これは人間や理想的にはマシンがあなたのAPIを発見し始めることができるエントリーポイントです。

HAL specificationによれば、リソース表現は、ここで記載されて"_links"と呼ばれるオプションのプロパティが含ま：

それは、そのプロパティ名リンク関係の種類（RFC5988によって定義 など）および値のいずれかであるているオブジェクトでありますリンクオブジェクトまたはリンクオブジェクトの配列 。

これらのリンクは、APIのハイパーメディア部分を表します。関係はIANA - 登録された関係か、あなた自身の拡張関係を使用することができます。

関係があいまいであってはなりません。彼らの名前はユニークでなければなりません。そのため、自分のドメインのURIを自分の関係の名前として使用することをお勧めします。これらのURIは、リレーションを表すリソースを識別し、APIドキュメント、関係の人間または機械で判読可能なドキュメントを含みます。

これは、/ordersリソースへの状態遷移を表すリレーションです。これには、応答の説明と説明が含まれている必要があります。 /ordersリソースは注文のリストを表し、number型の値を持つ "shippedToday"というプロパティを持っています。 http://yourdomain.com/docs/rels/ordersの下

HTTP/1.1 200 OK 
Content-Type: application/hal+json 

{ 
    "_links": { 
     "self": { "href": "/" }, 
     "http://yourdomain.com/docs/rels/orders": { "href": "/orders" }, 
    } 
} 

APIドキュメントがあるはずです。ここで

はGET/HTTP/1.1要求するための例の応答です。