RESTful Referenzdarstellungen - semantische Verknüpfung vs uri

9

Wir entwickeln eine RESTful-API, um die Kontoinformationen unserer Kunden zu öffnen. Wir haben Darstellungen, die Verweise auf andere Ressourcen enthalten, die sich auf die aktuelle Ressource beziehen. Dies geht auf eine Reihe von Best Practices zurück, die wir in öffentlichen APIs sowie in veröffentlichten Materialien finden konnten. Die Darstellungen können entweder XML oder JSON sein.

Beispielsweise hätten wir für eine Kontoressource Verweise auf die Adressen des Kontos und für eine paginierte Listenressource Verweise auf die erste, nächste und vorherige Seite.

Die API wurde zuerst unter Verwendung semantischer Links entwickelt, <link title="" rel="" href="" />wie in einem O'Reilly-Buch beschrieben, und in APIs von Netflix und Google verwendet. Als unsere QS-Ingenieure die Automatisierungssuite schreiben mussten, hatten sie Probleme, die Links zu deserialisieren. Wir haben jetzt einfachere Uri-String-Elemente vorgeschlagen, die in APIs von Facebook und Twitter verwendet wurden.

Unsere QS-Entwickler haben inzwischen ihre Deserialisierungsprobleme gelöst, aber ich habe immer noch Bedenken hinsichtlich der Benutzerfreundlichkeit der aktuellen API-Spezifikation mit semantischen Links. Unsere API wird hauptsächlich von unseren Kunden und einigen Partnerschaften mit Drittanbietern verwendet. Wir haben uns für REST entschieden, da die vorherige XML-RPC-API für unsere Kunden zu schwierig war.

tl; dr;

Frage:

Hat jemand, der eine semantische Linkdarstellung implementiert hat, Verbraucherprobleme mit dieser Schwierigkeit erlebt?

Update (21.06.): Ich habe mich entschlossen, bei semantischen Links zu bleiben und hoffe, dass die Verwirrung ein Randfall war. Ich werde versuchen, mich daran zu erinnern, die Frage mit unseren Erfahrungen zu beantworten, sobald die API bei einigen Verbrauchern verfügbar ist.

Bearbeiten: Beispiele hinzufügen

Semantisches Konto 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"
        }
    ]
}

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

Einfaches Konto JSON:

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

Einfaches Konto XML:

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

rest semantics

— Paul
quelle

Können Sie uns konkrete Beispiele für die ursprünglichen semantischen Verknüpfungen und die "einfacheren Uri-String-Elemente" geben? Es ist nicht besonders klar, was Sie mit diesen Begriffen meinen, insbesondere mit letzteren.

— Tom Anderson

Aktualisiert mit konkreten Beispielen. Ich kann auch Beispiele für die paginierten Listen / Sammlungen hinzufügen, wenn das hilft.

— Paul

3

Ich hätte lieber:

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

Dies eliminiert das Array und macht das Objekt überfahrbar (um die Adresse eines Kontos zu erhalten, z. B. in JavaScript, könnte man account.address.href sagen, anstatt alle Links zu durchlaufen und eine zu finden, die wie eine Adresse aussieht). Entsprechendes XML:

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

Was denkst du?

— Ville Immonen
quelle

1

Der Traum des Semantic Web ist, dass Links automatisch entdeckt werden können. Da der schwierige Teil darin besteht, die Verknüpfungen und ihre Verwendung zu verstehen, glaube ich, dass semantische Informationen nicht so nützlich sind.

Ich neige leicht zu den semantischen XML-Formularen, da das Attribut "rel" einen definierten Erweiterungsmechanismus für durch Leerzeichen getrennte Felder aufweist und "link" gut verstanden wird.

Als Verbraucher solcher APIs sehe ich keinen großen Unterschied.

— Andrew Dalke
quelle