RESTful reference representations - semantic link vs uri

Question

We're designing a RESTful API to open up our customer's account information. We have representations that contain references to other resources related to the current resource. This is from a number of best practices we were able to find in public APIs as well as published materials. The representations can be either XML or JSON.

For example for an account resource we would have references to the account's addresses and for a paginated list resource, we would have references to the first, next, and previous pages.

The API was first designed using semantic links <link title="" rel="" href="" /> as described in an O'Reilly book and used in APIs by Netflix and Google. When it came time for our QA engineers to write the automation suite, they had problems deserializing the links. We've now suggested simpler uri string elements which have been used in APIs by Facebook and Twitter.

Our QA enginners have since solved their deserialization issues, but I still have a concern of the ease of use of the current API spec with semantic links. Our API will primarily be consumed by our customers and some third-party partnerships and we've gone to REST because the previous XML-RPC API was too difficult for our consumers.

tl;dr;

Question:

Has anyone who has implemented a semantic link representation experienced consumer issues with the difficulty?

---

Update (6/21): I've decided to stay with semantic links and hope that the confusion was an edge case. I'll try to remember to answer the question with our experiences once the API is live with some consumers.

---

Edit: add examples

Semantic Account 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"
        }
    ]
}

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

Simple Account JSON:

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

Simple Account XML:

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

Answer 1

I would rather have:

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

This eliminates the array and makes the object traversable (to get the address of an account e.g. in JavaScript one could say account.address.href instead of looping through all links and finding one that looks like an address). Corresponding 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>

What do you think?

Answer 2

The dream of the semantic web is that links can be discovered automatically. Since the hard part is understanding the linkages and how to use them, I believe that semantic information isn't that useful.

I have a slight leaning towards the Semantic XML forms because the "rel" attribute has a defined extensibility mechanism of space-separated fields, and "link" is well-understood.

As a consumer of such APIs, I don't see much other difference.