RESTful референтні уявлення - семантична зв'язок проти урі

Ми розробляємо API RESTful для відкриття інформації про обліковий запис нашого клієнта. У нас є представлення, які містять посилання на інші ресурси, пов'язані з поточним ресурсом. Це з ряду найкращих практик, які нам вдалося знайти в публічних API, а також в опублікованих матеріалах. Представлення можуть бути або XML, або JSON.

Наприклад, для ресурсу облікового запису ми мали б посилання на адреси облікового запису, а на ресурс сторінки, що пакутує, ми мали б посилання на першу, наступну та попередню сторінки.

Спочатку API був розроблений з використанням семантичних посилань, <link title="" rel="" href="" />як описано в книзі O'Reilly, і використовуваних в API від Netflix та Google. Коли прийшов час, щоб наші інженери з якості контролю писали набір автоматизації, у них виникли проблеми з дезаріалізацією посилань. Зараз ми запропонували простіші елементи рядка Uri, які використовувались в API в Facebook та Twitter.

Наші інженери з QA з тих пір вирішили свої питання щодо десеріалізації, але я все ще хвилююся простотою використання поточної специфікації API із семантичними посиланнями. Наш API в основному буде споживатися нашими клієнтами та деякими сторонніми партнерськими відносинами, і ми перейшли до REST, оскільки попередній API XML-RPC був надто складним для наших споживачів.

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>

Я вважаю за краще:

{
  "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>

Як ти гадаєш?

Мрією семантичної павутини є те, що посилання можна виявити автоматично. Оскільки важкою частиною є розуміння зв’язків та способів їх використання, я вважаю, що семантична інформація не так корисна.

Я незначно схиляюся до форм Semantic XML, тому що атрибут "rel" має визначений механізм розширюваності полів, розділених простором, і "посилання" добре зрозуміло.

Як споживач таких API, я не бачу особливої ​​різниці.