RESTful reprezentacje referencyjne - link semantyczny vs. uri

Projektujemy interfejs API RESTful, aby otworzyć informacje o koncie klienta. Mamy reprezentacje zawierające odniesienia do innych zasobów związanych z bieżącym zasobem. Wynika to z wielu najlepszych praktyk, które udało nam się znaleźć w publicznych interfejsach API, a także w opublikowanych materiałach. Reprezentacjami mogą być XML lub JSON.

Na przykład dla zasobu konta mielibyśmy odniesienia do adresów konta, a dla paginowanego zasobu listy, mielibyśmy odniesienia do pierwszej, następnej i poprzednich stron.

Interfejs API został po raz pierwszy zaprojektowany przy użyciu łączy semantycznych, <link title="" rel="" href="" />jak opisano w książce O'Reilly, i został użyty w interfejsach API przez Netflix i Google. Kiedy przyszedł czas, aby nasi inżynierowie ds. Kontroli jakości napisali pakiet automatyzacji, mieli problemy z deserializacją łączy. Zasugerowaliśmy teraz prostsze elementy łańcucha uri, które były używane w interfejsach API przez Facebooka i Twittera.

Nasi inżynierowie ds. Kontroli jakości od tego czasu rozwiązali swoje problemy z deserializacją, ale nadal mam obawy o łatwość użycia bieżącej specyfikacji API z linkami semantycznymi. Nasz interfejs API będzie używany głównie przez naszych klientów i niektóre podmioty zewnętrzne, a my poszliśmy do REST, ponieważ poprzedni interfejs API XML-RPC był zbyt trudny dla naszych klientów.

tl; dr;

Pytanie:

Czy ktoś, kto zaimplementował semantyczną reprezentację linku, napotkał problemy konsumentów?

Aktualizacja (6/21): Postanowiłem pozostać z linkami semantycznymi i mam nadzieję, że zamieszanie było skrajnym przypadkiem. Postaram się pamiętać, aby odpowiedzieć na pytanie z naszymi doświadczeniami, gdy interfejs API zostanie udostępniony niektórym klientom.

Edycja: dodaj przykłady

Konto semantyczne 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"
        }
    ]
}

Konto semantyczne 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>

Proste konto JSON:

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

Proste konto XML:

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

Wolałbym mieć:

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

Eliminuje to tablicę i sprawia, że ​​obiekt jest w stanie przejść (aby uzyskać adres konta, np. W JavaScript, można powiedzieć: account.address.href zamiast zapętlać wszystkie linki i znaleźć taki, który wygląda jak adres). Odpowiadający 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>

Co myślisz?

Sen sieci semantycznej polega na tym, że linki mogą być odkryte automatycznie. Ponieważ trudną częścią jest zrozumienie powiązań i sposób ich wykorzystania, uważam, że informacje semantyczne nie są tak przydatne.

Opieram się nieco na semantycznych formach XML, ponieważ atrybut „rel” ma zdefiniowany mechanizm rozszerzalności pól oddzielonych spacją, a „link” jest dobrze zrozumiany.

Jako konsument takich interfejsów API nie widzę wiele innych różnic.