0

私はまだこの RESTFUL に慣れていないため、ブログなどを読んでいるので許してください...そして、それらはすべて異なる実装/ガイドラインを持っています。実際のガイドラインは、ハイパーメディアとは何かを指定するリチャードソン成熟度モデルだけです。

ハイパーメディア設計の利点は、ルート URL を介してマシン/ユーザーの対話を駆動する注釈とのリンクを持つことであり、リンクが変更されたときのように進化可能であり、べき等/安全な http 動詞などでキャッシュを強化することです...

私は RESTFUL API Web サービスを設計しようとしています。HAL、Collection+Json、Siren などの汎用メディア タイプを使用する予定です。今...

一般的なメディア タイプを使用すると、ペイロード、データ構造、または DTO オブジェクトなど、「多くの申請者を持つアプリケーション モデルと多くのアドレスを持つモデルなど」のようになります。

1) データ構造定義をどこかに指定する必要がありますか? または何らかのフォーム テンプレートですか。そのデータの定義を人間が読める形式で「someurl / doc？またはjsonスキーマのようなものを使用する必要がありますか？」のような例を見てきました。

2）私が見たいくつかの例では、データ項目を vcard/foaf などからのリンクのタイプで装飾しました。"名前": " http://xmlns.com/foaf/0.1/name ". どういう意味ですか？私が見るいくつかの例には、名前オブジェクトなどを説明するための someurl/doc#name への参照が似ています...

3) Application Model のペイロードが変わると、コントラクトのインタープリターが変わるということですか? したがって、SOAP のように、すべてのクライアントが以前と同じように壊れますか?

4) もう 1 つの選択肢として、実際の構造を形成する Name,Value,Prompt を持つコレクション + json アイテム オブジェクトのように、進化可能なアイテム構造を持つことができると思います。これにより、それを消費するクライアント側で最小限のコントラクトの変更が行われます。

オブジェクトをどのように設計すべきかについてアドバイスをお願いします。基本的に、質問を簡単にするために、複数のアドレスを持つ複数の申請者を持つアプリケーションオブジェクトがあると言います。

ジョシュ

4

1 に答える 1

3

現在のベスト プラクティスは、可能な限り新しいコンテンツ タイプを作成しないことです。

  1. あなたの聴衆に依存します。彼らが消費しやすいものを使用してください。スキーマを理解できる一般的な自動化されたエージェントですか、それとも API に特化して作業する開発者ですか。とにかく、人間が読めるドキュメントが常に必要になるので、そこから始めます。リクエスト本文を受け入れることを選択した場合application/x-www-form-urlencoded、HTML フォームは作業用テンプレートを提供する優れた方法です。
  2. これは、フィールドの「タイプ」を定義します。したがってname、 afoaf:nameは、呼び出されたフィールドnameに type の値が含まれていることを示していますhttp://xmlns.com/foaf/0.1/name。リソース記述形式である RDF について読み、Turtle や N3 などの表現を調べれば、これがより明確になります。owl:sameAsリンク関係はやなどの RDF プロパティと同じではありませんが、(単純な文字列ではなく) URI である関係の概念はそこから来ていますfoaf:name。どちらも有向グラフのエッジとして表されます。
  3. 詳しく説明してください。フィールドが追加/削除されたということですか、それともまったく異なるコンテンツ タイプですか? 後者は別のリソースであり、別の URI を持つべきだと私は主張します。クライアントは、リソースに加えられる将来の変更を理解するか、無視できる必要があります。
  4. あなたが提案したすべてのコンテンツ タイプは、この方法で進化できるはずです。それがまさにHATEOASの前提です。

あなたのデザインは、コレクションのリストを含み、それぞれがリーフ リソースのリストを含む、1 つのルート リソースを持つ単純なツリー構造のように見えます。複雑なことは何もないので、ここで何かが欠けているようです。

応募者とは、仕事に応募する人を意味し、アドレスとは、彼らが住んでいる場所または働いている場所 (たとえば、電子メール アドレスとは対照的に) を意味すると仮定します。以下のいくつかは明白かもしれませんが、この質問に出くわす可能性のある他の読者のために含めています.

HAL を使用した実装例は次のようになります。

リクエスト：

GET / HTTP/1.1
Host: example.com
Accept: application/hal+json

応答：

HTTP/1.1 200 OK

{ "_links": {
    "self": { "href": "/" },
    "http://example.com/docs/applicant": [
      { "href": "/applicant1" },
      { "href": "/applicant2" },
      { "href": "/applicant3" }]
} }

次に、クライアントは関係を持つハイパーリンクを探しますhttp://example.com/docs/applicant。これは単なる文字列であり、必要にfishmonkeygiraffe応じて指定できます。文字列を http URL にすることで、クライアントの開発者はドキュメントをより簡単に見つけることができます。一意の文字列: 独自のドメイン。クライアントがその中のハイパーリンク (<LINK> 要素と <A> 要素) を見つける方法を知っている限り、応答形式は HTML などのハイパーテキスト対応形式にすることができます。または、それらを HTTP リンクヘッダーで返すこともできます。ただし、取得したリソースをディスクに書き込む必要がある場合は、クライアントがそれらを格納する必要があります。

次に、クライアントは、見たいものを要求します。

GET /applicant1 HTTP/1.1
Host: example.com
Accept: application/hal+json

応答：

HTTP/1.1 200 OK

{ "_links": {
    "self": { "href": "/applicant1" },
    "http://example.com/docs/applicant-address": [
      { "href": "/applicant1/address1" },
      { "href": "/applicant1/address2" },
      { "href": "/applicant1/address3" }]
} }

明らかに、「applicant1」は、「applicants/1」や「vacancies/sweet-manager/applicants/dave-smith」など、任意の名前にすることができます。クライアントは、指定された URL に従うだけです。

次にクライアントは、http://example.com/docs/applicant-address取得するタイプのハイパーリンクを選択します。

GET /applicant1/address1 HTTP/1.1
Host: example.com
Accept: application/hal+json

応答：

HTTP/1.1 200 OK

{ "_links": {
    "self": { "href": "/applicant1/address1" },
    "edit-form": { "href": "/applicant1/address1/edit" },
    "http://example.com/docs/applicant": { "href": "/applicant1" }
  },

  "street": "5 Dungeon Drive",
  "town": "Snotty Hill",
  "county": "London",
  "postcode": "NE5 2LT",
  "country": "GB",
}

ここで、クライアントはアドレスを修正したいので、"edit-form" 関係を持つハイパーリンクをたどります: ( IANA リンク関係を参照)

GET /applicant1/address1/edit HTTP/1.1
Host: example.com
Accept: text/html

応答：

HTTP/1.1 200 OK

<!DOCTYPE HTML>
<form action="/applicant1/address1" method="POST">
  <input name="street" value="5 Dungeon Drive">
  et cetera
</form>

その結果：

POST /applicant1/address1 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

street=5%20Dungeon%20Drive&...

私が HAL を使用したのは、HAL が XML+XLink の JSON バージョンのようなものであり、SO の例を簡単に入力できるためです ;) つまり、ハイパーメディア対応の一般的な解析形式であり、それ以上のものではありません。すべての相互作用は、リンク関係によって導かれます。Web ブラウザは、rel="stylesheet"その関係が何を意味するかを知っているため、リンクをどうするかを知っています。上記の IANA 定義のリンク関係のリストは、最初に選択する必要があるものです (itemおよびcollection探しているものが十分に具体的でない場合は、あなたのセクターに関連するリンク関係の公開リストを見つけて (たとえば、市場のリーダーが公開している API を参照してください)、可能であればそれらを再利用してください。これにより、ツールはすべて同じリンク関係を探しているため、ツールが相互運用可能になります。質問の Dublin Core の例は、公的に定義された RDF プロパティの同様のリポジトリです。

ハイパーリンクの場合、結合 (契約) はクライアントとサイトの間ではなく、クライアントと一連の関係です。関係はできるだけよく知られている必要があります (これは、ウィキペディアが「ハイパーメディアの一般的な理解」と言うときに意味するものです)。
リソース フィールドについては、リソースを一般的に処理する場合は、RDF ベースのソリューションをお勧めします。これには、ビジネス ドメインに密接に対応するよく知られた RDF プロパティを使用します。JSON への RDF シリアル化はいくつか存在しますが、現時点では明確なリーダーはありません。この時点では、おそらく XML のみをサポートする方がよいでしょう。6 つの簡単なステップでの JSON から RDF へのブログ投稿は、RDF の基礎を学ぶ方法として洞察力があるかもしれません。

于 2013-06-12T09:32:33.177 に答える