Représentations de référence RESTful - lien sémantique vs uri

9

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>
rest semantics Paul
la source
Pourriez-vous nous donner des exemples concrets des liens sémantiques originaux et des "éléments de chaîne uri plus simples"? On ne sait pas très bien ce que vous entendez par ces termes, en particulier ces derniers.
Tom Anderson
Mis à jour avec des exemples concrets. Je peux également ajouter des exemples pour les listes / collections paginées si cela aide.
Paul

Réponses:

3

Je prefererais avoir:

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

Cela élimine le tableau et rend l'objet traversable (pour obtenir l'adresse d'un compte, par exemple en JavaScript, on pourrait dire account.address.href au lieu de parcourir tous les liens et d'en trouver un qui ressemble à une adresse). XML correspondant:

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

Qu'est-ce que tu penses?

Ville Immonen
la source
1

Le rêve du web sémantique est que les liens puissent être découverts automatiquement. Étant donné que la partie difficile consiste à comprendre les liens et à les utiliser, je pense que les informations sémantiques ne sont pas si utiles.

J'ai un léger penchant vers les formes XML sémantiques car l'attribut "rel" a un mécanisme d'extensibilité défini de champs séparés par des espaces, et "link" est bien compris.

En tant que consommateur de telles API, je ne vois pas beaucoup d'autre différence.

Andrew Dalke
la source