マイクロサービスアーキテクチャ（HAL、ALPS）のRestfulサービスのドキュメントを正しく設定する方法

Question

Microservicesを適切に設定する方法について多くの読者が読んでおり、最近のいくつかの概念を取り上げています。 HAL、ALPS、およびHALブラウザ。私は歴史的にSwagger UIを活用した事柄を文書化してきましたが、URL中心が適切な方法ではないことを理解するようになり、より新しい技術が必要とするリソースとリンクに関する文書を整理する必要があります。私はこれらの新しい概念の周りにかなりの知識のギャップを持っているので、私はこれらの技術がどのように連携しているかを正しく理解したかったので、それぞれについて学び、パズルに合わせることができます。

私の現在の理解は次のとおりです。

HALは - あなたがリンクを介して、あなたのAPIをナビゲートできるようになるJSONの上に、追加のフォーマットです。

ALPS - 資源・リンク中心のドキュメントの闊歩UIの交換 - それは私が私のリソース

HALブラウザを記述するための助けになる英語ベースの記述を提供させることができますJSONの上に、追加のフォーマットです。 HALとALPSを一緒に使う？

これらのテクノロジに関する私の現在の理解は正確か、一部の領域では不足していますか？また、私はALPSとHALがどのように相互作用しているかを十分に理解していません。私はhal + json形式とalps + json形式を認識していましたが、hal + alps + json形式は見ていません。

私が最後に取り上げたいのは、これらのリソースをどのように公開するのかです。通常、私はいつも非常にリーンなjsonメッセージに焦点を当てていましたが、予想通りにhal + json形式を送信していますか？

Answer 1

バディ！あなたがここで知覚しようとしている地獄です。ステップで説明しようとしましょう。

文書centricは、サービス間の移行を意味します。はい、Web上で情報を意味的に共有する（またはデータ型として理解する）必要があります。

手順：1 である以下に示すハイパーメディアすなわち、HTML、XML、JSON、HAL等たとえばJSONについて の任意の形態とすることができるデータ・タイプのメタデータと標準データ型のサービスのために使用されるプロトコル（HTTP）リンクを持つルートドキュメント。 'todos'と 'profile'はどちらもHALベースのハイパーメディアリンクであり、HALは現在のAPIを増やすだけです。

{ "_links" : { 
    "todos" : { 
     "href" : "http://localhost:8080/todos" 
    }, 
    "profile" : { 
     "href" : "http://localhost:8080/alps" 
    } 
    } 
} 

リソースのセマンティクスを指す可能性のあるリソースのリンクを示していることに注意してください。 HALの主な焦点は、リンク、プロパティ、および/または埋め込みのいずれかによってリソース/テンプレートをリンクすることです。 上記で説明した所要量は、主に、プロトコルレベルでの共有データ型のリンクです。

ステップ：2 ALPS上記JSONで意味アプリケーションレベルのアフォーダンスiは藤堂が何であるかを知っているが、どのように相互作用することがありますか？ Todoと対話するには、アプリケーションレベルの状態遷移が必要です。 リンクからナビゲートした 'todo' JSONを考えてみましょう。また、 'descriptors'や 'Type'（SEMANTIC、SAFE、UNSAFEなど）などの詳細なキーワードも表示します。

'id'プロパティは表現識別子になります。これらは独立したALPSの状態と遷移を適用するためのルールまたはルールです。

{ "version" : "1.0", 
    "descriptors" : [ { 
    "id" : "todo-representation", 
    "descriptors" : [ { 
     "name" : "description", 
     "doc" : { 
     "value" : "Details about the TODO item", 
     "format" : "TEXT" 
     }, 
     "type" : "SEMANTIC" 
    }, { 
     "name" : "title", 
     "doc" : { 
     "value" : "Title for the TODO item", 
     "format" : "TEXT" 
     }, 
     "type" : "SEMANTIC" 
    }, { 
     "name" : "id", 
     "type" : "SEMANTIC" 
    } ] 
    }, { 
    "id" : "get-todos", 
    "name" : "todos", 
    "type" : "SAFE", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "create-todos", 
    "name" : "todos", 
    "type" : "UNSAFE", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "delete-todo", 
    "name" : "todo", 
    "type" : "IDEMPOTENT", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "patch-todo", 
    "name" : "todo", 
    "type" : "UNSAFE", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "get-todo", 
    "name" : "todo", 
    "type" : "SAFE", 
    "rt" : "#todo-representation" 
    } ] 
} 

いくつかのリンクは、詳細slides about ALPSとRest Exampleにチェックする価値があります。これがあなたの理解を助けてくれることを願っています。

Answer 2

私はそれ自身のマイクロサービスごとに、APIのドキュメントurlを持っています。例：http://myservice1domain:8080/swagger-ui.html。私はALPSを使用していません。さらに、私はあなたが持っていなければならないと思うか、またはHALのものだけを具体的に公開できるのは、それらが応答データと結びついているからです。とにかくHALは、サンプルリクエストボディとして応答jsonを利用してスワッガーでユーザーに公開します。