10

RESTful Web サービスを進化させる適切な方法は、サービス用のカスタム メディア タイプを作成することであると、仲間の開発者 (現在は退職) に確信してもらいました。

例 application/vnd.acme.payroll.v1+json

このようにして、URI を変更せずに、使用するエンコーディングを指定するようにクライアントに指示できます。

このテクニックは良いものですか？通常、サービスはバージョンを URL に埋め込みます。

例 /acme/1.0/payroll/

特にDELETEはメディアタイプを強制しないように見えるため、クライアントにこのスキームを使用するよう強制するのは非常に困難でした

4

2 に答える 2

19

RESTful サービスで使用できる主要なシグナリング メカニズムがいくつかあります。

  • メディアの種類
  • リンク先のrelリソースの 。
  • Accept-Version/などのカスタム ヘッダーApi-Version。

これらにはそれぞれ異なる用途があり、API を設計する際にそれらを理解する方法を概説します。

メディアの種類

特定のリソースで可能な操作と、これらの操作のセマンティクスを示すために、多くの場合、カスタム メディア タイプが使用されます。私の意見では、これは正確ではなく、a のrel方が正確です。

カスタム メディア タイプは、データのタイプ、たとえばデータの形式や、特定の情報が具現化または埋め込まれている方法などを示す必要があります。カスタム メディア タイプを持つということは、API のコンシューマーがその特定の表現に密接に結合されていることを意味します。一方、より一般的なものを使用すると、 application/json「これは単なる JSON データです」と言われます。

通常、RESTful サービスには JSON だけでは十分ではありません。組み込みのリンク機能やリソース埋め込み機能がないためです。そこで、 HAL ( )のようなものがapplication/hal+json登場します。JSON を特殊化したものであり、まだ一般的な形式であり、アプリケーション固有ではありません。しかし、RESTful API を首尾一貫して表現するために必要な JSON の上に、リンクと埋め込みのセマンティクスをオーバーレイするだけで十分です。

リンク関係タイプ ( rels)

これにより、relsが得られます。私にとって、カスタム rel は、どのタイプのリソースが処理またはリンクされているかを知らせるのに最適な方法です。たとえばrel、ユーザー リソースのカスタムは であり、次のhttp://rel.myapi.com/user2 つの目的を果たします。

  • このキーは API 固有の知識であるため、API のクライアントは事前にこのキーを知っておく必要があります。たとえば、最初のリソースで利用可能で、HAL を使用してユーザー リソースにリンクしていた場合、クライアントは を介し​​てユーザー リンクを見つける可能性がありますinitialResource._links["http://rel.myapi.com/user"].href。
  • API クライアントを作成する開発者は、Web ブラウザーでその URI にアクセスし、そのリソースが API で何を表しているか (適用可能なメソッドやその機能など) の説明を取得できます。これは、私が言及した API 固有の知識を伝達するための非常に便利な方法です。この例については、http://rel.nkstdy.coを参照してください。

relを のような標準または準標準のメディア タイプと組み合わせると、application/hal+jsonメディア タイプで指定された統一フォーマットに従い、API 固有のセマンティクスが で定義されたリソースが得られますrel。これで、ほぼすべての場所に到達できます。

カスタム ヘッダー

残りの問題はバージョン管理です。古い URI を無効にせずに、クライアントが異なるバージョンのリソースをネゴシエートできるようにするにはどうすればよいでしょうか?

Restify Node.js フレームワークに着想を得た私たちのソリューションは、 2 つのカスタム ヘッダーです。Accept-VersionクライアントからのものでX-Api-Version、サーバーから (または、新しいRFC 6648Api-Versionに従って、次の Restify 2.0 リリースで)ほぼ一致します。それらが一致しない場合、結果は a になります。400 Bad Request

ここでは、カスタム メディア タイプがかなり一般的なソリューションであることを認めます。私の意見では、上記の考慮事項に照らして、それらは概念的にはあまり適していませんが、バージョン管理メカニズムとしてそれらを選択したとしても、何か変なことをすることはないでしょう. お気づきのように、それ以外のメソッドで使用すると、セマンティックな問題がいくつかGETあります。

心に留めておくべきことの 1 つは、真の RESTful システムでは、バージョン管理がそのような問題であってはならないということです。relリソースの表現が下位互換性のない方法で変更されたが、同じsを維持したい場合です。そのため、http://rel.myapi.com/friendリソースが突然そのフィールドを失い、usernameフィールドを獲得した場合id、それは資格があります。しかし、突然nicknameフィールドを取得した場合、それは下位互換性がないわけではないため、バージョン管理は必要ありません。また、API で「友達」の概念が「接続」などの概念に完全に置き換えられた場合、これは実際には下位互換性がないわけではありません。API コンシューマーはhttp://rel.myapi.com/friend、API のどこにも、従うべきリンクを見つけられなくなるからです。 .

于 2012-07-17T03:59:41.967 に答える
3

はい、良い選択肢です。あなたが正しく指摘したように、ペイロードに使用するエンコーディングを明確にし、URIを変更せずに両側で異なるバージョンのエンコーディングをネゴシエートできるようにします。

はい、クライアントがエンティティ本体とともに DELETE を送信する必要はありません。その場合、ペイロードデータが転送されないことを考えると、準拠した HTTP サーバーによって単に無視されると思います。クライアントは URI に対して DELETE を発行し、サーバーは成功したかどうかを示す応答コードを返します。シンプルでいい！サーバーが DELETE の後に何らかのデータを返したい場合は、自由に行うことができ、その際に応答のメディア タイプを指定する必要があります。

于 2012-07-17T02:25:29.187 に答える