Representaciones de referencia RESTful - enlace semántico vs uri

9

Estamos diseñando una API RESTful para abrir la información de la cuenta de nuestros clientes. Tenemos representaciones que contienen referencias a otros recursos relacionados con el recurso actual. Esto se debe a una serie de mejores prácticas que pudimos encontrar en API públicas, así como en materiales publicados. Las representaciones pueden ser XML o JSON.

Por ejemplo, para un recurso de cuenta tendríamos referencias a las direcciones de la cuenta y para un recurso de lista paginada, tendríamos referencias a las páginas primera, siguiente y anterior.

La API se diseñó primero utilizando enlaces semánticos <link title="" rel="" href="" />como se describe en un libro de O'Reilly y Netflix y Google lo utilizaron en las API. Cuando llegó el momento de que nuestros ingenieros de control de calidad escribieran la suite de automatización, tuvieron problemas para deserializar los enlaces. Ahora hemos sugerido elementos de cadena uri más simples que han sido utilizados en API por Facebook y Twitter.

Desde entonces, nuestros ingenieros de control de calidad han resuelto sus problemas de deserialización, pero todavía me preocupa la facilidad de uso de la especificación API actual con enlaces semánticos. Nuestra API será consumida principalmente por nuestros clientes y algunas asociaciones de terceros y hemos ido a REST porque la API XML-RPC anterior era demasiado difícil para nuestros consumidores.

tl; dr;

Pregunta:

¿Alguien que haya implementado una representación de enlace semántico ha experimentado problemas con los consumidores con la dificultad?

Actualización (6/21): he decidido quedarme con enlaces semánticos y espero que la confusión sea un caso extremo. Intentaré recordar responder la pregunta con nuestras experiencias una vez que la API esté activa con algunos consumidores.

Editar: agregar ejemplos

Cuenta semántica 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"
        }
    ]
}

Cuenta semántica 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>

Cuenta simple JSON:

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

Cuenta simple XML:

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

rest semantics

— Pablo
fuente

¿Podría darnos ejemplos concretos de los enlaces semánticos originales y los "elementos de cadena uri más simples"? No está terriblemente claro lo que quiere decir con esos términos, particularmente el último.

— Tom Anderson

Actualizado con ejemplos concretos. También puedo agregar ejemplos para las listas / colecciones paginadas si eso ayuda.

— Paul

3

Yo preferiria tener:

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

Esto elimina la matriz y hace que el objeto sea transitable (para obtener la dirección de una cuenta, por ejemplo, en JavaScript, se podría decir account.address.href en lugar de recorrer todos los enlaces y encontrar uno que parezca una dirección). XML correspondiente:

<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é piensas?

— Ville Immonen
fuente

1

El sueño de la web semántica es que los enlaces se pueden descubrir automáticamente. Como la parte difícil es comprender los vínculos y cómo usarlos, creo que la información semántica no es tan útil.

Tengo una ligera inclinación hacia las formas XML semánticas porque el atributo "rel" tiene un mecanismo de extensibilidad definido de campos separados por espacios, y "link" se entiende bien.

Como consumidor de tales API, no veo mucha otra diferencia.

— Andrew Dalke
fuente