RESTful Web APIs

Chapter 6. The Collection Pattern

Back in Chapter 2, I showed off a simple microblogging API that served representations with a media type of application/vnd.collection+json. The representations looked like this:

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

    "items" : [
      { "href" :
        "http://www.youtypeitwepostit.com/api/messages/21818525390699506",
        "data" : [
         { "name" : "text", "value" : "Test." },
         { "name" : "date_posted", "value" : "2013-04-22T05:33:58.930Z" }
        ],
        "links" : []
      },

      { "href" :
        "http://www.youtypeitwepostit.com/api/messages/3689331521745771",
        "data" : [
         { "name" : "text", "value" : "Hello." },
         { "name" : "date_posted", "value" : "2013-04-20T12:55:59.685Z" }
        ],
        "links" : []
      },

      { "href" :
        "http://www.youtypeitwepostit.com/api/messages/7534227794967592",
        "data" : [
         { "name" : "text", "value" : "Pizza?" },
         { "name" : "date_posted", "value" : "2013-04-18T03:22:27.485Z" }
        ],
        "links" : []
      }
    ],

    "template" : {
      "data" : [
         {"prompt" : "Text of message", "name" : "text", "value" : ""}
      ]
    }
  }
}

In this chapter, I’ll talk more about Collection+JSON,^[17] the standard that defines the structure of this document.

Collection+JSON is one of several standards designed not to represent one specific problem domain (the way Maze+XML does), but to fit a pattern—the collection—that shows up over and over again, in all sorts of domains. This standard makes a good example, because it’s a formalized version of the JSON-based APIs that first-time designers ...