Designing Collections

In every web project that you do at one point you will have to handle collections.

Collections are entities that are structurally or syntatically similar. Examples would include:

  • Users
  • Books
  • Apples

Collection of fruites

Collection of fruites

When designing collections it is very tempting to include all the attributes in the collection.

For example we may be tempted to provide something of this sort

{
  "products": {
    "link": {
      "-rel": "self",
      "-href": "http://www.example.org/catalog/products"
    },
    "automobile": {
      "id": "9001",
      "link": {
        "-rel": "self",
        "-href": "http://www.example.org/catalog/product/9001"
      },
      "make": "Smart",
      "model": "Fortwo Convertible",
      "year": "2009",
      "class": {
        "-classid": "small",
        "#text": "Small Car"
      },
      "mpg": {
        "city": "33",
        "highway": "41"
      },
      "drivetrain": "2WD",
      "list-price": {
        "-currency": "USD",
        "#text": "19495"
      }
    },
    "sailboat": {
      "id": "10101",
      "link": {
        "-rel": "self",
        "-href": "http://www.example.org/catalog/product/10101"
      },
      "make": "Jeanneau",
      "model": "Sunfast 3200",
      "year": "2008",
      "length": {
        "-unit": "ft",
        "#text": "32"
      },
      "hull-type": "fiberglass",
      "number-of-engines": "1",
      "list-price": {
        "-currency": "USD",
        "#text": "95995"
      }
    }
  }
}

In the above example, we included too much detail per item. Anyone trying to consume this particular resource is probably only interested in common properties of the collection.

{
  "products": {
    "link": {
      "-rel": "self",
      "-href": "http://www.example.org/catalog/products"
    },
    "product": [
      {
        "-type": "automobile",
        "id": "9001",
        "link": {
          "-rel": "self",
          "-href": "http://www.example.org/catalog/product/9001"
        },
        "make": "Smart",
        "model": "Fortwo Convertible",
        "year": "2009",
        "list-price": {
          "-currency": "USD",
          "#text": "19495"
        }
      },
      {
        "-type": "sailboat",
        "id": "10101",
        "link": {
          "-rel": "self",
          "-href": "http://www.example.org/catalog/product/10101"
        },
        "make": "Jeanneau",
        "model": "Sunfast   3200",
        "year": "2008",
        "list-price": {
          "-currency": "USD",
          "#text": "95995"
        }
      }
    ]
  }
}

In this example we have removed the extranous fields and a consumer of the collection can as such treat them as one.

In general to summarize a collection look for salient properties across the items in the collection.

Finally it is important to always include meta data of the collection. This includes the fields:

  • total size
  • size per page
  • current page
  • self link
  • prev
  • next

By including this data we give the quality of affordance, that is the resource describes itself and thus can be easily used by diverse clients.

Till next time, happy designing!

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Published by

jchencha

Software Project Manager