OEM、OpenAPIによって供給される休息/hateoasのためのmediatype
18559 ワード
今日は、ohm形式のドラフトを紹介したいと思いますOpenAPI ハイパーメディアコントロールを記述するには
オーム形式の説明
オーム仕様https://github.com/cbornet/ohm
オームブラウザhttps://raw.githack.com/cbornet/swagger-ui/ohm/dist/
サンプルオームアプリケーションhttps://rest-openapi-demo.herokuapp.com/api ( https://github.com/cbornet/sample-rest-app ) RESTとHypermediaのより多くの読書: マイクAmundsenによって「ハイパーメディアAPIで自由なために自治と回復力を得てください:」http://amundsen.com/talks/2020-10-apiworld/2020-10-apiworld-hypermedia.pdf
ロイ・フィールドの残りの論文https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
ロイフィールディングによって「残りAPIはハイパーテキスト駆動でなければなりません:」https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
オーム形式の説明
TL博士: OpenAPI Hypermediaの形式はohmと呼ばれます.メディアタイプはapplication/ohm+json 定義は以下の通りです:
{
"content": <JSON representation of the resource>,
"controls": <An OpenAPI Specification (OAS) in JSON format containing the possible operations from this state>
}
... そしてそれです.あなたは既にこの形式として小さな形式の定義を見たことがありますか?
例えば、AのためのオームメッセージPerson コレクションを持つリソースAddress 以下のようになります.
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"controls": {
"openapi": "3.0.1",
"info": {
"title": "rest",
"version": "0.0.1"
},
"paths": {
"/api/addresses/1": {
"get": {
"summary": "John Doe's address"
}
}
}
}
}
コンテンツフィールドには、通常のジェーンドーと呼ばれる人を記述する情報が含まれていますapplication/json メディアタイプ.とcontrols フィールドは、ジェーンdoeのアドレスへのリンクを持つOASです.そして、経路、方法、引数の事前知識なしでその人のアドレスから人へナビゲートするために、オームのクライアントを使用できます.を使用する必要があります.
書き込み操作を記述するためにohmを使うこともできます.
GET /api/orders/106
{
"content": {
"id": 106,
"product": "Licensed Concrete Keyboard",
"cost": 571.0,
"customer": {
"id": 1,
"name": "Ricky Swift"
}
},
"controls": {
"openapi": "3.0.1",
"paths": {
"/api/orders/106": {
"put": {
"summary": "Update order 106",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
}
},
"delete": {
"summary": "Delete order 106"
}
},
"/api/customers/1": {
"get": {
"summary": "Get this order's customer (id=1)"
}
}
},
"components": {
"schemas": {
"Order": {
"type": "object",
"properties": {
"cost": {
"type": "number",
"example": 571.0
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
}
}
}
}
}
}
}
}
}
これは、プット操作がリソースを削除するために使用することができる古典的なCRUDリソースまたは削除する1つです.OpenAPIはPUT操作の期待されるリクエスト本体とそのメディアタイプを完全に記述するのに役立ちます.
このポストの残りの部分は、より良いAPIをビルドするためにこのフォーマットを使用する方法を説明します.
ohmは、残りのメディアタイプです
まず、真の残りのアプリケーションは何ですか(また、残りのレベル3)と呼ばれる?既に知っている場合は、この全体の章をスキップすることができます.しかし、私は彼らが休息APIをすると言う多くの人々と話をします、しかし、彼らがすることが実はHTTPの上で実際に古いRPC(遠隔手続き呼び出し)であるということを理解しないでください.
Quoting Roy Fielding , 残りの発明者
"What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API."
RESTの主要な制約は、したがって、アプリケーション状態(Hooeoas)のエンジンとしてHypermediaを使用することです.それは1930年代の中心にあったREST dissertation そして、名前「表現的な状態移動」でさえ、それはこの建築様式がとてもユニークにすることです.HateEAsは、サーバーから受け取ったメッセージがアプリケーションを駆動するために必要なすべての情報を含んでいることを意味します.それは正確にどのようにナビゲーションをHTMLドキュメントで動作する:あなたは他のリンクとフォームを使用して他の状態から移動します.それで、あなたがウェブに行って、あなたのブラウザーでHTML文書を進めるとき、毎日、休みは使われます.しかし、あなたがHTTP + JSON APIを通してウェブサービスを呼ぶとき、決して.
OHMは、2014年までのHiEeoasサポートを提供しますcontrols フィールド.HTMLと比較すれば、アンカーリンク( GET )とフォーム( POST )と等価です.しかし、OpenAPIに依存しているので、すべてのHTTPメソッドを使用できます.The content フィールドはリソースの表現を含むすべてのDIVSとCSSと等価です.ある意味では、OEMはマシン(簡単に解析する)に向けたフォーマットであるのに対し、HTMLは人間に向けられている(グラフィカルな情報で).
ときにオームの形式で残りのアプローチを使用するには？
ロイフィールディングの論文の時点で、Webアプリケーションの状態は完全にサーバーに存在していた.
しかし、ブラウザとモバイル革命のJavaScriptの出現では、アプリケーションの状態マシンは、現在様々なクライアントの中に移動している必要はありませんもうサーバーから状態遷移を転送する必要はありません.それで、我々はちょうどサーバーからウェブサービスを公開して、我々がOpenAPIで説明するRPC HTTP呼び出しでそれらを使用します.
ORMなどの残りの形式では、アプリケーションの状態管理をサーバーに戻すことができます.これは、クライアントまたはブラウザの種類(ブラウザ、モバイル、…)の間の部品またはアプリケーション全体のロジックを共有する可能性を与えます.そして、ネイティブのモバイルアプリケーションでの作業時に主要な利得であるクライアントを更新することなく、アプリケーションのロジックを進化させることができます.
HTMLに比べて利点は、ビューはまだクライアントによって構築されているので、ネイティブのモバイルなどの非HTMLクライアントで使用することができますです.
また、アプリケーションを公開していないWebサービスもあります.その場合、アプリケーションは我々がコントロールしていないクライアントにとどまります.それは消費者のためのブラウジング可能なAPIを提供するので、彼らはより良いAPIの呼び出しの自然連鎖を理解することができますが、あまりにも少ない利点としてハイパーメディアリンクを追加するために必要な追加の作業に比べてそれを見ることができます.
同じエンドポイントをアプリケーションとサービスの両方に使用する場合を除きます.その場合、OHMはアプリケーションのためにhateoasを提供します、そして、あなたのクライアントはまだcontent 使用する場所と同じapplication/json MediaType.
WebサービスのためのRESTとOEMを使用するもう一つの利点は、クライアントに利用可能なすべての操作を一覧表示するエンドポイントを提供できることです.あなたがあなたのウェブサイトに存在するすべての関連と形で一つのHTMLページを提供するならば、少しのように.クライアントとAPIの間で共有されたセマンティックを持つoperationId ), URLと要求を動的に構築するクライアントを作成できます.また、サーバー上のURLやパラメータの配置を変更しても適応できます.もちろん、非RESTクライアントがAPIを使用する場合は、APIをバージョンアップし、これらのクライアントの後方互換性を確保する必要があります.
OEMの主な意図は、システム間の完全な自動化と相互運用性を提供することではありません.これは確かにJSON - LDのようなものを使って語彙を追加することで構築できます.私は、これに関して意見と考えを得ることに非常に興味があります.
オームブラウザの力
OEMのようなREST形式の1つの大きな利点は、メディアタイプをサポートする任意のアプリケーションを理解するジェネリッククライアントを構築できることです.例えば、オームのためにOHM Browser これは、HTTP呼び出し応答を表示する代わりに実行するときにリンクをナビゲートする修正Swagger UIです(デフォルトで指すサンプルアプリケーションはHeroku Freeティアでホストされていますので、目を覚ますには少し時間がかかることがあります).😅)
あなたはそれをテストすることができますsample OHM application Jipsterを使用して構築することができますを作成し、読む、更新、ナビゲーションリンクを削除し、また、ページをサポートしています.このアプリケーションのソースコードがありますhere .
どのようにオームは他の残りのフォーマットと比較しますか？
多くのhateoasフォーマットは、ナビゲーションシステム(GET)をサポートしていて、リモートシステム(post、put、...)を変更するだけのアクションをサポートしていません.OpenAPIに依存して、オームはすべての一般的なHTTPメソッドをサポートします.また、完全に操作リンク、その呼び出しパラメータを記述し、メッセージでそれらを使用する方法に関するドキュメントを埋め込むことができます.
オームはすべてをサポートH Factors マイクAmundsenによって記述されます.
あなたは既にOpenAPIを知っている場合は、新しい形式を学ぶ必要はありません.
OHPをサポートするために再利用することができるOpenAPIの風景の中にオープンソースのツールがたくさんあります.たとえば、オームのブラウザは、swaggerのUIに基づいて、サンプルアプリケーションを使用すると、Springfoxによって生成された…を使用します.
HTTP + JSON APIをOGMに移行するのは比較的簡単です.
結論
私は本当に残りのWebアプリケーションに多くをもたらすことができると信じています.うまくいけば、OpenAPIに精通しているならオームは簡単に採用できます.それを試してみて、それをビルド何を与えることを躊躇しないでください!
次のステップは、ヘルパーJavaライブラリ(サンプルアプリケーションコードから抽出する必要がある)によって開始されるECOシステムを拡張することです.私はまた、春のhateoasと統合することが可能であるべきだと思うので、それを見てみましょう.あなたがヘルパーライブラリを持っているだろう心の言語がある場合は私に到達することを躊躇しないでください.ああ、私はあなたがRPCのHTTP APIをRESTとして呼び出し続ける場合、あなたを非難しません😉 !
あなたは私の上に従うことができます.
オームリンク
{
"content": <JSON representation of the resource>,
"controls": <An OpenAPI Specification (OAS) in JSON format containing the possible operations from this state>
}
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"controls": {
"openapi": "3.0.1",
"info": {
"title": "rest",
"version": "0.0.1"
},
"paths": {
"/api/addresses/1": {
"get": {
"summary": "John Doe's address"
}
}
}
}
}
GET /api/orders/106
{
"content": {
"id": 106,
"product": "Licensed Concrete Keyboard",
"cost": 571.0,
"customer": {
"id": 1,
"name": "Ricky Swift"
}
},
"controls": {
"openapi": "3.0.1",
"paths": {
"/api/orders/106": {
"put": {
"summary": "Update order 106",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
}
},
"delete": {
"summary": "Delete order 106"
}
},
"/api/customers/1": {
"get": {
"summary": "Get this order's customer (id=1)"
}
}
},
"components": {
"schemas": {
"Order": {
"type": "object",
"properties": {
"cost": {
"type": "number",
"example": 571.0
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
}
}
}
}
}
}
}
}
}
まず、真の残りのアプリケーションは何ですか(また、残りのレベル3)と呼ばれる?既に知っている場合は、この全体の章をスキップすることができます.しかし、私は彼らが休息APIをすると言う多くの人々と話をします、しかし、彼らがすることが実はHTTPの上で実際に古いRPC(遠隔手続き呼び出し)であるということを理解しないでください.
Quoting Roy Fielding , 残りの発明者
"What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API."
RESTの主要な制約は、したがって、アプリケーション状態(Hooeoas)のエンジンとしてHypermediaを使用することです.それは1930年代の中心にあったREST dissertation そして、名前「表現的な状態移動」でさえ、それはこの建築様式がとてもユニークにすることです.HateEAsは、サーバーから受け取ったメッセージがアプリケーションを駆動するために必要なすべての情報を含んでいることを意味します.それは正確にどのようにナビゲーションをHTMLドキュメントで動作する:あなたは他のリンクとフォームを使用して他の状態から移動します.それで、あなたがウェブに行って、あなたのブラウザーでHTML文書を進めるとき、毎日、休みは使われます.しかし、あなたがHTTP + JSON APIを通してウェブサービスを呼ぶとき、決して.
OHMは、2014年までのHiEeoasサポートを提供します
controls フィールド.HTMLと比較すれば、アンカーリンク( GET )とフォーム( POST )と等価です.しかし、OpenAPIに依存しているので、すべてのHTTPメソッドを使用できます.The content フィールドはリソースの表現を含むすべてのDIVSとCSSと等価です.ある意味では、OEMはマシン(簡単に解析する)に向けたフォーマットであるのに対し、HTMLは人間に向けられている(グラフィカルな情報で).ときにオームの形式で残りのアプローチを使用するには？
ロイフィールディングの論文の時点で、Webアプリケーションの状態は完全にサーバーに存在していた.
しかし、ブラウザとモバイル革命のJavaScriptの出現では、アプリケーションの状態マシンは、現在様々なクライアントの中に移動している必要はありませんもうサーバーから状態遷移を転送する必要はありません.それで、我々はちょうどサーバーからウェブサービスを公開して、我々がOpenAPIで説明するRPC HTTP呼び出しでそれらを使用します.
ORMなどの残りの形式では、アプリケーションの状態管理をサーバーに戻すことができます.これは、クライアントまたはブラウザの種類(ブラウザ、モバイル、…)の間の部品またはアプリケーション全体のロジックを共有する可能性を与えます.そして、ネイティブのモバイルアプリケーションでの作業時に主要な利得であるクライアントを更新することなく、アプリケーションのロジックを進化させることができます.
HTMLに比べて利点は、ビューはまだクライアントによって構築されているので、ネイティブのモバイルなどの非HTMLクライアントで使用することができますです.
また、アプリケーションを公開していないWebサービスもあります.その場合、アプリケーションは我々がコントロールしていないクライアントにとどまります.それは消費者のためのブラウジング可能なAPIを提供するので、彼らはより良いAPIの呼び出しの自然連鎖を理解することができますが、あまりにも少ない利点としてハイパーメディアリンクを追加するために必要な追加の作業に比べてそれを見ることができます.
同じエンドポイントをアプリケーションとサービスの両方に使用する場合を除きます.その場合、OHMはアプリケーションのためにhateoasを提供します、そして、あなたのクライアントはまだcontent 使用する場所と同じapplication/json MediaType.
WebサービスのためのRESTとOEMを使用するもう一つの利点は、クライアントに利用可能なすべての操作を一覧表示するエンドポイントを提供できることです.あなたがあなたのウェブサイトに存在するすべての関連と形で一つのHTMLページを提供するならば、少しのように.クライアントとAPIの間で共有されたセマンティックを持つoperationId ), URLと要求を動的に構築するクライアントを作成できます.また、サーバー上のURLやパラメータの配置を変更しても適応できます.もちろん、非RESTクライアントがAPIを使用する場合は、APIをバージョンアップし、これらのクライアントの後方互換性を確保する必要があります.
OEMの主な意図は、システム間の完全な自動化と相互運用性を提供することではありません.これは確かにJSON - LDのようなものを使って語彙を追加することで構築できます.私は、これに関して意見と考えを得ることに非常に興味があります.
オームブラウザの力
OEMのようなREST形式の1つの大きな利点は、メディアタイプをサポートする任意のアプリケーションを理解するジェネリッククライアントを構築できることです.例えば、オームのためにOHM Browser これは、HTTP呼び出し応答を表示する代わりに実行するときにリンクをナビゲートする修正Swagger UIです(デフォルトで指すサンプルアプリケーションはHeroku Freeティアでホストされていますので、目を覚ますには少し時間がかかることがあります).😅)
あなたはそれをテストすることができますsample OHM application Jipsterを使用して構築することができますを作成し、読む、更新、ナビゲーションリンクを削除し、また、ページをサポートしています.このアプリケーションのソースコードがありますhere .
どのようにオームは他の残りのフォーマットと比較しますか？
多くのhateoasフォーマットは、ナビゲーションシステム(GET)をサポートしていて、リモートシステム(post、put、...)を変更するだけのアクションをサポートしていません.OpenAPIに依存して、オームはすべての一般的なHTTPメソッドをサポートします.また、完全に操作リンク、その呼び出しパラメータを記述し、メッセージでそれらを使用する方法に関するドキュメントを埋め込むことができます.
オームはすべてをサポートH Factors マイクAmundsenによって記述されます.
あなたは既にOpenAPIを知っている場合は、新しい形式を学ぶ必要はありません.
OHPをサポートするために再利用することができるOpenAPIの風景の中にオープンソースのツールがたくさんあります.たとえば、オームのブラウザは、swaggerのUIに基づいて、サンプルアプリケーションを使用すると、Springfoxによって生成された…を使用します.
HTTP + JSON APIをOGMに移行するのは比較的簡単です.
結論
私は本当に残りのWebアプリケーションに多くをもたらすことができると信じています.うまくいけば、OpenAPIに精通しているならオームは簡単に採用できます.それを試してみて、それをビルド何を与えることを躊躇しないでください!
次のステップは、ヘルパーJavaライブラリ(サンプルアプリケーションコードから抽出する必要がある)によって開始されるECOシステムを拡張することです.私はまた、春のhateoasと統合することが可能であるべきだと思うので、それを見てみましょう.あなたがヘルパーライブラリを持っているだろう心の言語がある場合は私に到達することを躊躇しないでください.ああ、私はあなたがRPCのHTTP APIをRESTとして呼び出し続ける場合、あなたを非難しません😉 !
あなたは私の上に従うことができます.
オームリンク
OEMのようなREST形式の1つの大きな利点は、メディアタイプをサポートする任意のアプリケーションを理解するジェネリッククライアントを構築できることです.例えば、オームのためにOHM Browser これは、HTTP呼び出し応答を表示する代わりに実行するときにリンクをナビゲートする修正Swagger UIです(デフォルトで指すサンプルアプリケーションはHeroku Freeティアでホストされていますので、目を覚ますには少し時間がかかることがあります).😅)
あなたはそれをテストすることができますsample OHM application Jipsterを使用して構築することができますを作成し、読む、更新、ナビゲーションリンクを削除し、また、ページをサポートしています.このアプリケーションのソースコードがありますhere .
どのようにオームは他の残りのフォーマットと比較しますか？
多くのhateoasフォーマットは、ナビゲーションシステム(GET)をサポートしていて、リモートシステム(post、put、...)を変更するだけのアクションをサポートしていません.OpenAPIに依存して、オームはすべての一般的なHTTPメソッドをサポートします.また、完全に操作リンク、その呼び出しパラメータを記述し、メッセージでそれらを使用する方法に関するドキュメントを埋め込むことができます.
オームはすべてをサポートH Factors マイクAmundsenによって記述されます.
あなたは既にOpenAPIを知っている場合は、新しい形式を学ぶ必要はありません.
OHPをサポートするために再利用することができるOpenAPIの風景の中にオープンソースのツールがたくさんあります.たとえば、オームのブラウザは、swaggerのUIに基づいて、サンプルアプリケーションを使用すると、Springfoxによって生成された…を使用します.
HTTP + JSON APIをOGMに移行するのは比較的簡単です.
結論
私は本当に残りのWebアプリケーションに多くをもたらすことができると信じています.うまくいけば、OpenAPIに精通しているならオームは簡単に採用できます.それを試してみて、それをビルド何を与えることを躊躇しないでください!
次のステップは、ヘルパーJavaライブラリ(サンプルアプリケーションコードから抽出する必要がある)によって開始されるECOシステムを拡張することです.私はまた、春のhateoasと統合することが可能であるべきだと思うので、それを見てみましょう.あなたがヘルパーライブラリを持っているだろう心の言語がある場合は私に到達することを躊躇しないでください.ああ、私はあなたがRPCのHTTP APIをRESTとして呼び出し続ける場合、あなたを非難しません😉 !
あなたは私の上に従うことができます.
オームリンク
私は本当に残りのWebアプリケーションに多くをもたらすことができると信じています.うまくいけば、OpenAPIに精通しているならオームは簡単に採用できます.それを試してみて、それをビルド何を与えることを躊躇しないでください!
次のステップは、ヘルパーJavaライブラリ(サンプルアプリケーションコードから抽出する必要がある)によって開始されるECOシステムを拡張することです.私はまた、春のhateoasと統合することが可能であるべきだと思うので、それを見てみましょう.あなたがヘルパーライブラリを持っているだろう心の言語がある場合は私に到達することを躊躇しないでください.ああ、私はあなたがRPCのHTTP APIをRESTとして呼び出し続ける場合、あなたを非難しません😉 !
あなたは私の上に従うことができます.
オームリンク
Reference
この問題について(OEM、OpenAPIによって供給される休息/hateoasのためのmediatype), 我々は、より多くの情報をここで見つけました https://dev.to/cbornet/ohm-the-mediatype-for-rest-hateoas-powered-by-openapi-2abaテキストは自由に共有またはコピーできます。ただし、このドキュメントのURLは参考URLとして残しておいてください。
Collection and Share based on the CC Protocol