Representações de referência RESTful - link semântico vs uri

9

Estamos projetando uma API RESTful para abrir as informações da conta de nossos clientes. Temos representações que contêm referências a outros recursos relacionados ao recurso atual. Isso é resultado de várias práticas recomendadas que encontramos nas APIs públicas e nos materiais publicados. As representações podem ser XML ou JSON.

Por exemplo, para um recurso de conta, teríamos referências aos endereços da conta e, para um recurso de lista paginada, teríamos referências às páginas da primeira, da próxima e da anterior.

A API foi projetada usando links semânticos, <link title="" rel="" href="" />conforme descrito em um livro da O'Reilly e usada nas APIs da Netflix e do Google. Quando chegou a hora de nossos engenheiros de controle de qualidade escreverem o pacote de automação, eles tiveram problemas para desserializar os links. Sugerimos agora elementos mais simples de uri string que foram usados ​​em APIs pelo Facebook e Twitter.

Desde então, nossos engenheiros de controle de qualidade resolveram seus problemas de desserialização, mas ainda me preocupo com a facilidade de uso da especificação atual da API com links semânticos. Nossa API será consumida principalmente por nossos clientes e algumas parcerias de terceiros e fomos ao REST porque a API XML-RPC anterior era muito difícil para nossos consumidores.

tl; dr;

Questão:

Alguém que implementou uma representação de link semântico enfrentou problemas com o consumidor com a dificuldade?


Atualização (21/6): Decidi ficar com links semânticos e espero que a confusão seja um caso extremo. Tentarei lembrar de responder à pergunta com nossas experiências assim que a API estiver disponível para alguns consumidores.


Editar: adicionar exemplos

JSON da conta semântica:

{
    "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 da conta semântica:

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

JSON de conta simples:

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

XML simples da conta:

<account>
    <username>paul</username>
    <addresses>http://example.com/account/paul/addresses</addresses>
    <history>http://example.com/account/paul/history</history>
</account>
Paulo
fonte
Você poderia nos dar exemplos concretos dos links semânticos originais e dos "elementos mais simples da string da uri"? Não está muito claro o que você quer dizer com esses termos, principalmente o último.
Anderson
Atualizado com exemplos concretos. Também posso adicionar exemplos para as listas / coleções paginadas, se isso ajudar.
Paul

Respostas:

3

Eu preferiria ter:

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

Isso elimina a matriz e torna o objeto atravessável (para obter o endereço de uma conta, por exemplo, em JavaScript, pode-se dizer account.address.href em vez de percorrer todos os links e encontrar um que se pareça com um endereço). XML correspondente:

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

O que você acha?

Ville Immonen
fonte
1

O sonho da web semântica é que os links possam ser descobertos automaticamente. Como a parte difícil é entender os vínculos e como usá-los, acredito que as informações semânticas não são tão úteis.

Eu tenho uma ligeira inclinação para os formulários XML Semânticos, porque o atributo "rel" possui um mecanismo de extensibilidade definido de campos separados por espaço e o "link" é bem conhecido.

Como consumidor dessas APIs, não vejo muita outra diferença.

Andrew Dalke
fonte