Stiamo progettando un'API RESTful per aprire le informazioni sull'account dei nostri clienti. Abbiamo rappresentazioni che contengono riferimenti ad altre risorse relative alla risorsa corrente. Ciò deriva da una serie di best practice che siamo riusciti a trovare nelle API pubbliche e nei materiali pubblicati. Le rappresentazioni possono essere XML o JSON.
Ad esempio per una risorsa account avremmo riferimenti agli indirizzi dell'account e per una risorsa elenco impaginato, avremmo riferimenti alla prima, alla successiva e alle pagine precedenti.
L'API è stata inizialmente progettata utilizzando i collegamenti semantici <link title="" rel="" href="" /> come descritto in un libro di O'Reilly e utilizzato nelle API di Netflix e Google. Quando è arrivato il momento per i nostri ingegneri del controllo qualità di scrivere la suite di automazione, hanno avuto problemi nella deserializzazione dei collegamenti. Ora abbiamo suggerito elementi stringa uri più semplici che sono stati usati nelle API da Facebook e Twitter.
I nostri esperti di controllo qualità hanno da allora risolto i loro problemi di deserializzazione, ma continuo a preoccuparmi della facilità di utilizzo dell'attuale specifica API con collegamenti semantici. La nostra API verrà principalmente utilizzata dai nostri clienti e da alcune partnership di terze parti e siamo passati a REST perché la precedente API XML-RPC era troppo difficile per i nostri consumatori.
tl; dr;
Domanda:
Qualcuno che ha implementato una rappresentazione del collegamento semantico ha riscontrato problemi con la difficoltà del consumatore?
Aggiornamento (6/21): Ho deciso di rimanere con collegamenti semantici e spero che la confusione fosse 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
JSON account semantico:
{
"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 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>