Wrestling With The Immaturity of Level 3 REST

This guest post comes from Matthew Bishop, senior architect of Elastic Path, a provider of digital commerce software for enterprises.

This post explores the challenges we faced in building out our own commerce API and how we wrestled with the general immaturity of Level 3 REST.

We wanted to create an easy-to-use API that can be used in a wide variety of contexts from mobile devices, websites and set top boxes. This type of API demanded that capabilities be provided in a Resource-centric model rather than other models like Services or MVC. This gave us the opportunity to "start over" and re-imagine commerce in a more holistic, yet straightforward user-centric domain. Rather than publishing the capabilities into the API, we created new resources that provided state based on these capabilities.

As an example, our internal product model has a wide variety of product options, configurations, bundling options and merchandizing rules. The API, however, boils these down to products and components that can have selectable features. By unifying these in the API, the client developer is not burdened with knowing the difference between a configurable bundle and a multi-sku product. They just know that a product has selectable options. The internal capabilities are retained in our Commerce Manager tooling because they make sense given the goals for each product, but the API consumer is not aware of these differences. This approach allows us to create new, innovative productization strategies without forcing the clients to update along with the new merchandizing features.

The biggest challenge we faced overall was the lack of maturity in Level 3 REST. The key aspect of Level 3 REST that we solved in our API was managing the links between resources. This key aspect of REST is really important because it gives the client developer a way to write apps that know the names of related data and actions without having to know the addresses of these links or how to build them. It's like moving from Assembly language to C; in Assembler one cares a lot about how memory addresses are structured. In C, you don't care so much about addresses, you care about the names of things instead. The compiler takes care of the addresses for you.

For our commerce API, we standardized several concepts in Level 3 REST by giving them clear names and places to live in the Representation. For instance, all links live in one place: a "links" array at the root of the representation. Links go nowhere else. This makes it easy for a client dev to find links regardless of where the representation came form. Another concept we standardized was the link names themselves; links that are POSTable end with the term "action" so a client developer can understand what to do with a link that is used to create new representations or execute state. Our API has other similar standardizations that normalize the representations across the API; this makes it faster to understand and use.

In my next post, I will delve into how we made our commerce API scale for global commerce needs.

Be sure to read the next Best Practices article: Overcoming Our Inner Data Integration Conflicts