RESTful ссылочные представления - семантическая ссылка против URI

9

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

Например, для ресурса учетной записи у нас будут ссылки на адреса учетной записи, а для ресурса списка с нумерацией страниц - ссылки на первую, следующую и предыдущие страницы.

API был сначала разработан с использованием семантических ссылок, <link title="" rel="" href="" />как описано в книге О'Рейли, и использовался в API Netflix и Google. Когда нашим инженерам по обеспечению качества пришло время написать пакет автоматизации, у них возникли проблемы с десериализацией ссылок. Теперь мы предложили более простые строковые элементы URI, которые были использованы в API Facebook и Twitter.

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

ТЛ; др;

Вопрос:

Кто-нибудь, кто реализовал семантическое представление ссылок, сталкивался с трудностями потребителей?

Обновление (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>

rest semantics

— Павел
источник

Не могли бы вы дать нам конкретные примеры оригинальных семантических связей и «более простых элементов строки 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

Мечта о семантической сети заключается в том, что ссылки могут быть обнаружены автоматически. Поскольку сложная часть заключается в понимании связей и их использовании, я считаю, что семантическая информация не так полезна.

Я немного склоняюсь к формам Semantic XML, потому что атрибут rel имеет определенный механизм расширяемости полей, разделенных пробелами, и «link» понятен.

Как потребитель таких API, я не вижу большой разницы.

— Эндрю Далке
источник