RESTful参照表現-セマンティックリンクとURI


9

お客様のアカウント情報を公開するためのRESTful APIを設計しています。現在のリソースに関連する他のリソースへの参照を含む表現があります。これは、公開APIや公開資料で見つけたいくつかのベストプラクティスからのものです。表現は、XMLまたはJSONのいずれかです。

たとえば、アカウントリソースの場合、アカウントのアドレスへの参照があり、ページ番号付きリストリソースの場合、最初、次、および前のページへの参照があります。

APIは<link title="" rel="" href="" />、O'Reillyの本に記載されているセマンティックリンクを使用して最初に設計され、NetflixとGoogleによってAPIで使用されました。QAエンジニアがオートメーションスイートを作成するときがきたとき、リンクの逆シリアル化に問題がありました。FacebookとTwitterのAPIで使用されている、より単純なuri文字列要素を提案しました。

私たちのQA技術者たちは、それ以来、逆シリアル化の問題を解決しましたが、セマンティックリンクでの現在のAPI仕様の使いやすさにはまだ不安があります。以前のXML-RPC APIはユーザーにとって難しすぎたため、私たちのAPIは主にお客様と一部のサードパーティパートナーシップによって使用されます。RESTに移行しました。

tl; dr;

質問:

セマンティックリンク表現を実装した人が、困難を伴う消費者の問題を経験しましたか?


アップデート(6/21):セマンティックリンクを使用することにし、混乱がエッジケースであることを期待します。APIが一部のコンシューマーでライブになったら、私たちの経験で質問に答えることを忘れないでください。


編集:例を追加

セマンティックアカウントJSON:

{
    "username": "paul",
    "links": [
        {
            "title": "addresses",
            "rel": "related",
            "href": "http://example.com/account/paul/addresses"
        },
        {
            "title": "history",
            "rel": "related",
            "href": "http://example.com/account/paul/history"
        }
    ]
}

セマンティックアカウントXML:

<account>
    <username>paul</username>
    <link title="addresses" rel="related" href="http://example.com/account/paul/addresses" />
    <link title="history" rel="related" href="http://example.com/account/paul/history" />
</account>

単純なアカウントJSON:

{
    "username": "paul",
    "addresses": "http://example.com/account/paul/addresses"
    "history": "http://example.com/account/paul/history"
}

単純なアカウントXML:

<account>
    <username>paul</username>
    <addresses>http://example.com/account/paul/addresses</addresses>
    <history>http://example.com/account/paul/history</history>
</account>

元のセマンティックリンクの具体例と、「単純なuri文字列要素」を教えていただけませんか。それらの用語、特に後者の意味を明確に理解することはできません。
トムアンダーソン

具体例で更新されました。ページ付けされたリスト/コレクションの例も追加できます。
ポール

回答:


3

私はむしろ:

{
  "username": "paul",
  "address": {
      "rel": "related",
      "href": "http://example.com/account/paul/addresses"
  },
  "history" {
      "rel": "related",
      "href": "http://example.com/account/paul/history"
  }
}

これにより、配列が削除され、オブジェクトが通過可能になります(たとえば、JavaScriptですべてのリンクをループしてアドレスのように見えるリンクを見つける代わりに、account.address.hrefと言うことができます)。対応するXML:

<account>
    <username>paul</username>
    <addresses>
        <link rel="related" href="http://example.com/account/paul/addresses" />
    </addresses>
    <history>
        <link rel="related" href="http://example.com/account/paul/history" />
    </history>
</account>

どう思いますか?


1

セマンティックWebの夢は、リンクを自動的に発見できることです。難しいのは、リンケージとその使用方法を理解することなので、セマンティック情報はそれほど役に立たないと思います。

「rel」属性にはスペースで区切られたフィールドの拡張メカニズムが定義されており、「リンク」はよく理解されているため、私はセマンティックXMLフォームに少し傾いています。

そのようなAPIの消費者として、私は他の多くの違いを見ることはありません。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.