Why the / ?

The IWC utilizes forward slashes to signify hierarchy of resources. Borrowing from REST, IWC uses the / to show the pathing of a resource relative to its API. This naming schema translates well for coupling backend requests with IWC resources both against IWC & non-IWC backends.

The IWC relates resources based on their path, if a reference /a calls its list action (covered in the following tutorial Resource Collections) and resources /a/b and /a/c exist on the IWC Bus, the reference will receive notification that resources /a/b and /a/c exist.

Abstracting Resources

In the previous tutorials, IWC resource interaction has been on the individual resource level (set, get, delete, and watch). When structuring IWC resources, it is ideal apply abstraction where possible. IWC resources should be unique only when necessary. For example, if the IWC is used to create a centralized shopping cart, a non-abstracted IWC resource may look as so:

Centralized Resource: Poorly Structured

API: Data API
Resource: /shoppingCart

Value: {
  items: [
    {
      upc: 031719199112,
      price: 20.00,
      store: "amazon.com",
      quantity: 1
    },
    {
      upc: 043396281288,
      price: 5.99,
      store: "bestbuy.com",
      quantity: 5
    }
  ],
  total: 49.95,
  count: 6
}

A relatively simple resource, holds an array of items in the shopping cart, total cost, and total amount of items.

Note: The IWC has no direct affiliation with Amazon or Best Buy. Their websites are used in this tutorial simply for example purposes. The use-cases described below are fictional and are not actually implemented.

IWC Action's and example code on utilizing this resource structure follows in the next tutorial Resource Collections.

Scenario

A web application, named MyCart, is utilizing the above Data API resource, /shoppingCart, to aggregate a user's shopping list across multiple websites. Each of these websites use the IWC to update the shoppingCart whenever the user adds/removes/updates quantity of an item they wish to purchase. This lets the web application give the user a breakdown of how much they will be spending at each store. Each store utilizes the /shoppingCart to populate the website's unique shopping cart with items in /shoppingCart pertaining to said site.

Pros

Simple logic in MyCart. Only have to watch /shoppingCart for changes to update GUI.

Cons

Interaction with cart items not intuitive.
- If increasing the quantity of an an item in the cart is desired, a set action has to be called with the entire value of /shoppingCart with the one property changed being said item's quantity.
A website does not hold any sense of control over its resource contribution.
- If amazon.com's IWC client wants to increase quantity of an item, its directly modifying the same resource as bestbuy.com.
- This doesn't break functionality, but makes API development confusing and resource collision likely.

Abstracted Resources

Rather than stuffing all of the shopping cart details into /shoppingCart, consider the following resource structure:

Amazon Generated Resources

Amazon shoppingCart

API: Data API
Resource: /shoppingCart/amazon

Value: {
  total: 20.00,
  count: 1
}

Amazon shoppingCart item

API: Data API
Resource: /shoppingCart/amazon/031719199112

Value: {
  upc: 031719199112,
  price: 20.00,
  store: "amazon.com",
  quantity: 1
}

If the Amazon website creates and maintains resources for each item type in the shopping cart, it can update quantities on a item by modifying the resource at /shoppingCart/amazon/<UPC>. This makes deleting as simple as calling the delete action on /shoppingCart/amazon/<UPC> as well.

The /shoppingCart/amazon resource is a resource generated by the Amazon website to populate the summary its shopping cart across multiple open amazon.com windows. This utilizes resource filtering covered in the Resource Collections tutorial.

Best Buy Generated Resources

Best Buy shoppingCart

API: Data API
Resource: /shoppingCart/bestbuy

Value: {
  total: 29.95,
  count: 5
}

Best Buy shoppingCart item

API: Data API
Resource: /shoppingCart/bestbuy/043396281288

Value: {
  upc: 043396281288,
  price: 5.99,
  store: "bestbuy.com",
  quantity: 5
}

Best Buy follows the same common structuring of IWC resources as Amazon.

MyCart Generated

API: Data API
Resource: /shoppingCart

Value: {
  total: 49.95,
  count: 6
}

MyCart tracks and updates the highest-level resource /shoppingCart based on total items in any websites shopping cart running IWC. This utilizes resource filtering covered in the Resource Collections tutorial.

Improvements

By structuring the shopping cart resources with the above abstraction, the MyCart application can now easily modify specific website shopping cart items. It can increment the quantity of /shoppingCart/bestbuy/043396281288 without causing any state changes in the Amazon website. This is because the Amazon website does not care about any resources with a /shoppingCart/bestbuy prefix.

This resource structure would scale well for additional website additions, when the shopping cart items grows, the in-memory size of /shoppingCart does not. If Ebay (also not IWC affiliated) decides to add IWC for data sharing, and follows the resource naming convention with /shoppingCart/ebay, myCart will automatically benefit from ebay's resources without changing any code.