Rappresentazioni di riferimento RESTful - link semantico vs uri

Stiamo progettando un'API RESTful per aprire le informazioni sull'account dei nostri clienti. Abbiamo rappresentazioni che contengono riferimenti ad altre risorse correlate alla risorsa corrente. Questo deriva da una serie di buone pratiche che siamo riusciti a trovare nelle API pubbliche e nei materiali pubblicati. Le rappresentazioni possono essere XML o JSON.

Ad esempio, per una risorsa dell'account avremmo riferimenti agli indirizzi dell'account e per una risorsa dell'elenco impaginato, avremmo riferimenti alla prima, alla successiva e alla pagina precedente.

L'API è stata inizialmente progettata utilizzando collegamenti semantici <link title="" rel="" href="" />come descritto in un libro di O'Reilly e utilizzata nelle API da Netflix e Google. Quando è arrivato il momento per i nostri ingegneri addetti al controllo qualità di scrivere la suite di automazione, hanno avuto problemi a deserializzare i collegamenti. Ora abbiamo suggerito elementi di stringa uri più semplici che sono stati utilizzati nelle API da Facebook e Twitter.

I nostri ingegneri addetti al QA hanno risolto i loro problemi di deserializzazione, ma ho ancora una preoccupazione per la facilità d'uso delle attuali specifiche API con collegamenti semantici. La nostra API sarà utilizzata principalmente dai nostri clienti e da alcune partnership di terze parti e siamo andati a REST perché la precedente API XML-RPC era troppo difficile per i nostri consumatori.

tl; dr;

Domanda:

Qualcuno che ha implementato una rappresentazione di collegamento semantico ha avuto problemi con i consumatori con questa difficoltà?

Aggiornamento (21/06): ho deciso di rimanere con collegamenti semantici e spero che la confusione sia un caso limite. Cercherò di ricordare di rispondere alla domanda con le nostre esperienze una volta che l'API è in diretta con alcuni consumatori.

Modifica: aggiungi esempi

Conto semantico 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 dell'account semantico:

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

Account semplice JSON:

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

XML account semplice:

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

Preferirei avere:

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

Ciò elimina l'array e rende percorribile l'oggetto (per ottenere l'indirizzo di un account, ad esempio in JavaScript, si potrebbe dire account.address.href invece di scorrere tutti i collegamenti e trovarne uno che assomigli a un indirizzo). XML corrispondente:

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

Cosa ne pensi?

Il sogno del web semantico è che i collegamenti possono essere scoperti automaticamente. Poiché la parte difficile è comprendere i collegamenti e come usarli, credo che le informazioni semantiche non siano così utili.

Ho una leggera inclinazione verso le forme XML semantiche perché l'attributo "rel" ha un meccanismo di estensibilità definito di campi separati da spazio, e "link" è ben compreso.

Come consumatore di tali API, non vedo molte altre differenze.