Nous concevons une API RESTful pour ouvrir les informations de compte de nos clients. Nous avons des représentations qui contiennent des références à d'autres ressources liées à la ressource actuelle. Cela provient d'un certain nombre de meilleures pratiques que nous avons pu trouver dans les API publiques ainsi que dans les documents publiés. Les représentations peuvent être XML ou JSON.
Par exemple, pour une ressource de compte, nous aurions des références aux adresses du compte et pour une ressource de liste paginée, nous aurions des références aux pages première, suivante et précédente.
L'API a d'abord été conçue à l'aide de liens sémantiques <link title="" rel="" href="" />
comme décrit dans un livre O'Reilly et utilisée dans les API par Netflix et Google. Lorsque le moment est venu pour nos ingénieurs QA d'écrire la suite d'automatisation, ils ont eu des problèmes pour désérialiser les liens. Nous avons maintenant suggéré des éléments de chaîne uri plus simples qui ont été utilisés dans les API par Facebook et Twitter.
Nos ingénieurs QA ont depuis résolu leurs problèmes de désérialisation, mais je reste préoccupé par la facilité d'utilisation de la spécification API actuelle avec les liens sémantiques. Notre API sera principalement consommée par nos clients et certains partenariats tiers et nous sommes passés à REST parce que l'ancienne API XML-RPC était trop difficile pour nos consommateurs.
tl; dr;
Question:
Quelqu'un qui a implémenté une représentation de lien sémantique a-t-il rencontré des problèmes de consommation avec la difficulté?
Mise à jour (6/21): J'ai décidé de rester avec les liens sémantiques et j'espère que la confusion était un cas limite. Je vais essayer de me souvenir de répondre à la question avec nos expériences une fois que l'API sera en ligne avec certains consommateurs.
Modifier: ajouter des exemples
Compte sémantique 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 du compte sémantique:
<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>
Compte simple JSON:
{
"username": "paul",
"addresses": "http://example.com/account/paul/addresses"
"history": "http://example.com/account/paul/history"
}
XML de compte simple:
<account>
<username>paul</username>
<addresses>http://example.com/account/paul/addresses</addresses>
<history>http://example.com/account/paul/history</history>
</account>