お客様のアカウント情報を公開するための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>