HATEOASは、URL構造を多かれ少なかれ自由に変更する能力のほか、発見可能性と分離のために何を提供しますか？

最近、アプリケーション状態のエンジン（HATEOAS）としてのハイパーメディアについて読んでいます。これは、Web APIを「真にRESTful」とする制約です。基本的に、現在の状態から可能な遷移へのすべての応答にリンクを含めることになります。

HATEOASが私の理解に基づいていることを説明させてください。何かを見逃した場合は、訂正してください。

/
    GET: {
        "_links": {
            "child": [
                { "href": "http://myapi.com/articles", "title": "articles" }
            ]
        }
    }

/articles?contains=HATEOAS
    GET: {
        "_items": [
            { "uri": "http://myapi.com/articles/0", "title": "Why Should I Care About HATEOAS?" },
            { "uri": "http://myapi.com/articles/1", "title": "HATEOAS: Problem or Solution?" }
        ],
        "_links": {
            "self": { "href": "http://myapi.com/articles", "title": "articles" },
            "parent": { "href": "http://myapi.com/", "title": "home" }
        }
    }

    POST: {
        "title": "A New Article",
        "body": "Article body",
        "tags": [ "tag1", "tag2" ]
    }

/articles/0
    GET: {
        "title": "Why Should I Care About HATEOAS?",
        "body": "Blah blah blah"
        "tags": [ "REST", "HATEOAS" ],
        "_links": {
            "self": { "href": "http://myapi.com/articles/0", "title": "article" },
            "parent": { "href": "http://myapi.com/articles", "title": "articles" }
        }
    }

HATEOASは2つの主な利点を提供すると主張されています。

1. サービス全体がルートURIから検出可能であるため、ドキュメントは不要です。

2. クライアントはサーバーから切り離され、サーバーはURI構造を自由に変更できるようになりました。これにより、APIバージョン管理の必要がなくなります。

しかし、私の考えでは、サービスはそのURI構造よりもはるかに多くのことです。効果的に使用するには、次のことも知っておく必要があります。

• 使用できるクエリパラメータと可能な値
• JSON / XML / POST / PATCH / etcリクエストで送信する必要があるドキュメントの構造
• サーバーによって送信された応答の構造
• 発生する可能性のあるエラー
• ...

上記に基づいて、HATEOASは発見可能性と結合の問題のごく一部しか解決しません。上記の4つの側面を文書化する必要がありますが、それらはクライアントがサーバーに強く結合しているためです。クライアントの破損を回避するには、引き続きAPIをバージョン管理する必要があります。

それが提供する唯一の利点は、URL構造を多かれ少なかれ自由に変更できることです（ところで、「クールURIは変わらない」という原則はどうなりましたか？）。私の理解は正しいですか？

あなたの本能はほとんど正しいと思います。自明ではないWebアプリケーションの場合、クライアントは実行しているセマンティクスと構文に注意を払わなければならないため、これらの宣言された利点はそれほど素晴らしいものではありません。

しかし、それは、アプリケーションをHATEOASの原則に準拠させるべきではないという意味ではありません！

HATEOASとはどういう意味ですか？これは、原則としてWebサイトのようにアプリケーションを構成し、複雑なスキーマをダウンロードすることなく、必要なすべての操作を検出できることを意味します。（洗練されたWSDLスキーマはすべてをカバーできますが、それらがカバーする頃には、事実上すべてのプログラマーが理解する能力を超えています。

HATEOASは単にリッチリンクを意味するものではありません。これは、HTTP規格のエラーメカニズムを使用して、何が間違っていたかをより正確に示すことを意味します。「waaah！」で応答する必要はありません。代わりに、実際に何が間違っていたのか、クライアントがそれに対して何をするのかを説明する文書を提供できます。また、意味支えるようなものOPTIONS要求（クライアントは、彼らが使用することができますどのようなHTTPメソッドを見つけるすることを可能にする標準的な方法）とコンテンツタイプの交渉を応答の形式は、クライアントが処理できる形式に適合させることができるようになっています。説明文を入れることを意味します（または、おそらくそれへのリンク）クライアントが知らない場合に、自明でないケースでシステムを使用する方法を調べることができるようにします。説明テキストは人間が読むことも、機械で読むこともできます（必要に応じて複雑にすることもできます）。最後に、クライアントはリンクを合成しません（クエリパラメーターを除く）。クライアントは、リンクを指定した場合にのみリンクを使用します。

リンク用の優れたメモリとHTTP標準の百科事典的な知識を持ち、それ以外のことを知らないユーザー（HTMLの代わりにJSONまたはXMLを読むことができるため、少し奇妙な）がサイトを閲覧することを考える必要があります行う。

そしてもちろん、コンテンツタイプネゴシエーションを使用して、アプリケーションが使用できるHTML（5）/ JSクライアントを提供できます（ブラウザーが受け入れる準備が整っている場合）。結局のところ、RESTful APIが適切であれば、その上に実装するのは「簡単」なはずです。

HATEOASには、RESTful APIが何であるかを定義する2番目の柱、つまり標準化されたメディアタイプが必要です。ロイ・フィールディング自身が言った

REST APIは、リソースを表すために使用されるメディアタイプを定義する際に、その記述的な努力のほとんどすべてを費やす必要があります。

移行を明示的に定義する標準化されたメディアタイプと、リソースを相互にポイントするハイパーテキストを使用して、クライアントを中断せずに任意の形式を取ることができるリソースグラフを作成できます。Webの作業と同様、実際には、ドキュメント間にリンクがあり、ドキュメントはそれらのリンクをたどる方法を定義するHTMLで記述されています。<a href>はGET、<form>GETまたはPOST（およびGETの場合に使用するURLテンプレートを定義）、<link type="text/css">GET ...などです。これは、ブラウザーが任意の構造化されたHTMLページとWebをナビゲートする方法です。

あなたがしたすべてのポイント

• 使用できるクエリパラメータと可能な値
• JSON / XML / POST / PATCH / etcリクエストで送信する必要があるドキュメントの構造
• サーバーによって送信された応答の構造
• 発生する可能性のあるエラー

標準化されたメディアタイプの定義によって対処されるべきポイントです。もちろん、これははるかに難しく、「REST」APIを定義するときにほとんどの人が考えることではありません。ビジネスエンティティを取得し、その属性をJSONドキュメントに押し込んでRESTful APIを作成することはできません。

もちろん、RESTが「複雑なSOAPyの代わりにHTTPを使用する」ことを意味するように何らかの形で希薄化されました。HTTPとHyperTextを使用するだけではRESTfulにはなりません。これはほとんどの人が間違っていることです。

これは必ずしも悪いことではありません。RESTは、長期的な保守性と進化性と引き換えに、パフォーマンスと開発の容易さを犠牲にします。これは、大規模な企業向けアプリケーション統合のために作られました。ハードコーディングされたJSON構造を持つ小さなWeb APIが必要な場合があります。アドホックWeb APIであるRESTとは呼ばないでください。そして、それはそれが悪いことを意味するのではなく、RESTの制約に従おうとしないことを意味します。

参考文献

• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• http://martinfowler.com/articles/richardsonMaturityModel.html

このヘルプが少し明確になることを願っています:)

どんな種類のリクエストを送信するかについてのより多くの情報を含む、より豊かな応答を提供しようとするいくつかのハイパーメディア形式があります。

次に、サイレンドキュメントの例を示します。

{
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 42, 
      "itemCount": 3,
      "status": "pending"
  },
  "entities": [
    {
      "class": [ "info", "customer" ],
      "rel": [ "http://x.io/rels/customer" ], 
      "properties": { 
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [
        { "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
      ]
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "http://api.x.io/orders/42" },
    { "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },
    { "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
  ]
}

ご覧のとおり、関連する呼び出し方法に関する情報actionsがメッセージで提供されています。この情報を解釈することにより、クライアントは変更に対する抵抗力が強くなります。

relsが、固定語彙からではなく、検索可能なURIである場合、特に強力になります。

HATEAOSサービスには「ドキュメントはもう必要ありません」とどこで読みましたか？あなたが言うように、あなたはまだリンクのセマンティクスを文書化する必要があります。ただし、HATEOASを使用すると、ほとんどのURIの構造を文書化する必要がないため、永久に保持する必要がありません。

HATEOASにより、サービスの実装者は、クライアントが依存するURIの小さなセットを変更することなく、実装を大幅に効率的に変更およびスケーリングできます。多数のセットよりも少数のエントリポイントを変更せずに保持する方が簡単です。したがって、サービスへのパブリックエントリポイントの数を減らし、サブリソース（HATEOAS）へのリンクを動的に提供することは、非HATEOASサービスよりも「Cool URIs not change」を実際にサポートします。

（HATEOAS）、Web APIを「真にRESTful」にするために主張されている制約

それを真のREST APIにする唯一のことは、単一の制約ではなく、すべての制約を満たすことです。

しかし、私の考えでは、サービスはそのURI構造よりもはるかに多くのことです。効果的に使用するには、次のことも知っておく必要があります。

それが、他の制約、自己記述的なメッセージなどが必要な理由です...

クライアントの破損を回避するには、引き続きAPIをバージョン管理する必要があります。

どのように試しても、APIをバージョン管理する必要があります。RESTクライアントでは、メッセージを説明するRDF語彙に基づいて、何かをしたいページ、どのリンクをたどり、どのプロパティを収集する必要があるかを知る必要があります。その単語から何かを置換または削除する必要がある場合、おそらくすべてのクライアントが壊れてしまい、新しいバージョンが必要になります。したがって、RESTは早期に公開する必要のあるものではないと思います（そして、APIを絶えず変更している間にモデルを把握する必要があります）。最初に構築できる安定したドメインモデルが必要です...