RESTful Web APIs

Chapter 12. Resource Description and Linked Data

The data formats I’ve covered in this book are used primarily to allow resources to talk about themselves. That is, a client sends a GET request to the URL of a resource and receives a representation of that very resource. I’m calling this the representation strategy.

But a representation of resource A may also have something to say about resource B. This simple Collection+JSON document is a representation of one resource (a collection) but it has something to say about two other resources (the items in the collection):

{ "collection":
  {
    "version" : "1.0",
    "href" : "http://www.youtypeitwepostit.com/api/",

    "items" : [

      { "href" : "/api/messages/21818525390699506",
        "data": [
          { "name": "text", "value": "Test." }
        ]
      },

      { "href" : "/api/messages/3689331521745771",
        "data": [
          { "name": "text", "value": "Hello." }
        ]
      }
    ]
  }
}

I’m calling this the description strategy. With the description strategy, a representation spends most of its time talking about resources other than the resource it’s a representation of.

All hypermedia formats mix the representation and description strategies to some extent, but there’s a family of formats that focuses heavily on the description strategy: formats inspired by the Resource Description Framework (RDF) data model and associated with the Semantic Web movement.

I didn’t cover these formats in Chapter 10 because, from a REST point of view, they’re weird. A pure description strategy violates the Fielding ...