Architecture Roadmap: Do You Know Where You’re Going?

For any software product, having a clear vision of what it looks like is an important aspect for how it gets done. Seems pretty obvious, but all too often a product starts out as one thing and ends up as something else. Many factors can contribute to this, and one of them is that the stewards of the product can lose the vision they had for the product in the first place.

There is also a delicate balance at play with software products, and it’s the line between these two sides:

  1. Delivering features that lead to sales
  2. Delivering those features on a solid technical foundation

If you’ve been around long enough, you know that most products are built with features being the overwhelming priority. Features sell, plan and simple, and initially it can be the lifeblood of a product. But at some point, features become a zero-sum game and can lead to a bloated product where 80% of the “must-have” features aren’t actually used by its customers.

Whether that happens or not, the trick is being able to put in place an underlying technical platform that helps you to continue pushing the product forward. And they key to this is an Architecture Roadmap.

A Vision Reborn

Backstory time. A little over a year ago I joined Znode and basically spent my first month asking questions from anyone who would give me five minutes. Questions about the Multifront product, its history, how it got to this point, what are its strengths and weaknesses, who our customers were, what were their challenges, how do we market and sell it, where do our partners fit in, what is the out of box experience, and on and on. I asked questions from all angles.

What emerged from those discussions was a new vision for where the Multifront product should go. It needed to change from a standalone application into a true enterprise-class ecommerce engine platform. Someone put it to me this way: this will be like trying to change the wings and navigation system of an airplane full of people, but the plane must remain in flight while doing it. Yes, something like that.

An Architecture Roadmap Is The Key

In order to accomplish this monumental feat, we needed a plan, so I began curating a list of technical to-dos that would have an impact in the Multifront transformation. Over time, this simple to-do list morphed into a broader architectural roadmap, with buy-in not only from the development team, but also sales and marketing and Znode’s leadership team. This architecture roadmap is our guide to know where we are going and how we will get there.

30 Items, 40 Revisions

As of this writing, our Architecture Roadmap is on revision #40 and contains 30 items. Many of these things are big-ticket items, a couple are pie-in-the-sky types of things, while others are smaller in scope. But the size of these items is not what matters. What matters is that they exist and are visible to everyone in the company, which helps foster discussions and planning for future releases.

Again, it’s all about knowing where we’re going.

More to Come

This post kicks off my next series, where I’ll dive into the details for some of the items on our Architecture Roadmap. Stay tuned.

Click to learn more about the Znode Multifront architecture and framework


Responsive Design: Crafting an Experience for Everyone

The phrase “responsive web design” is still somewhat of a buzzword when it comes to building web sites. However, responsive web design is not a feature that you add on to your web site to make it mobile-friendly. Responsive design is just how you build web sites in a multi-device world. The question of “should we go responsive” shouldn’t even be a question because the answer is always “yes,” and that’s why the new MVC version of the Multifront ecommerce platform includes an example storefront that was built from beginning to end using responsive techniques.

Responsive design is not a feature.

The obvious advantage to responsive web design its ability to display well on devices of varying size, from phones to tablet to desktops. Of course, there are thousands of different devices out there in the wild – even in your office – and it’s impossible to account for them all…and you’re not supposed to.

The big difference with responsive design over how sites have been designed in the past is that you cannot worry about tiny details. The term “pixel perfect” is no longer valid when it comes to web design. You’re shooting for “usable” when it comes to a responsively designed web site, but that doesn’t have to mean boring or generic. It just means that you can’t worry about the positioning of an element between two different Android phones. It’s not going to look the same and it’s not intended to. Ultimately the design needs to be usable and communicate clearly, so the extra whitespace that appears on the big phone and not the small phone is not a concern, bug or problem.

Separating your concerns

Depending on where you sit in the development chain, the fact that responsive design relies on a single code base could be a good thing or a bad. I favor the former because managing two separate code bases for the same product is just more trouble than it’s worth. Before too long you’ll find one version is way out of sync with the other, giving your customers a very inconsistent experience between devices. You may also find yourself with two different products going in opposite directions, and that’s not going to help anyone.

Using the same code base for every experience doesn’t mean you can’t selectively load data, it just means you handle it all up front rather than having the server sniff a browser and do a bunch of domain switching and project loading. And when we’re talking about an online store, there’s probably little reason to have different markup for different devices. When going responsive you design and build once, but that means you have to consider every part while you work.

A tailored experience

The one aspect of responsive design that makes a huge impact on the user experience is that it requires you to think about the design and usability of your site on many devices. But since you’re considering device sizes from the beginning, you can be confident that the content on your site will be treated properly regardless of screen size. You’ll find yourself with a much better web site in the end when you build this way, but there are some trade-offs.

The need to consider different sizes does require more design effort from your staff but it’s to the tune of weeks, not months or years. There is little-to-no extra overhead when building a responsive site compared to a non-responsive or separate code base sites. Plus, the work flow for responsive design is going to get better and more efficient as we all adopt it as the correct way to build a web site. Don’t avoid design discussions and decisions. Embrace them for what they are – a chance to make your web site and your product better for everyone.

Designing for performance

Last but not least, the one thing you can’t skimp on when talking about building responsively is site performance. It’s no secret that a web site needs to be as fast a possible, and responsive doesn’t change that. But going responsive does mean you have to consider the performance for every page, every view and every interaction because you don’t know if the customer is on their phone standing in line at the grocery store, or if they’re on their couch watching television.

Performance needs to be part of the design process, not an afterthought or optimization routine applied when you’re all done. Think about the size of files, images and consider every plug-in and add-on you’re thinking about using. The question should always be asking is, can we do without this?

If anything, building and designing responsively is about whittling away the things you don’t need until you get to the true needs of your customers. Once you get there you’ll find you have a great experience for everyone regardless what type of device they’re using.


API Series: Help and Documentation

There are a lot of traits that make an API great. Easily consumable, predictable, discoverable, wide open, and a consistent URL design are the first that come to mind. But an often overlooked and undervalued area is documentation. Without proper documentation, developers are left to fend for themselves trying to figure out how to use an API, which is both time-consuming and error-prone. We’ve all been there, frustrated by an API and its lack of documentation.

Of course, there are some shining examples of API documentation done right – the Stripe API and the Github API immediately come to mind. Both are formatted and laid out well, easy to read, and contain all necessary information required to use their respective APIs.

For the Znode API, we knew from the beginning that documentation would play a major factor, and in fact, we quite often used other API docs as inspiration (in particular the Stripe API). We wanted users of the Znode API to feel at home and comfortable, and one of the best ways to do that is by providing clear, understandable documentation.

In fact, we went so far as to make the Znode API documentation simply *part* of the API itself (you can see a version of it at api.znode.com). There is no Word document or PDF file that you have to read through to know how to use the API. The API is a living, breathing artifact that you can understand as you use the various endpoints. The homepage of the API lays out all of the parts that make up the API and what they mean, while each endpoint help page lists all of its supported features and sample data to get you up to speed quickly (which also serve as the perfect reference material).

The Znode API documentation is as vital to the API as the API itself, because in our eyes, they are one and the same.


API Series: Authentication

Security is a big deal with anything on the web, and APIs are no exception. Many times an API provider requires authentication to verify the caller has permissions to make a request and usually some type of access key is required. The Znode API follows this same convention and makes it easy to authenticate requests to its endpoints.

Like many other APIs, the Znode API uses basic authentication with the Authorization header to validate requests. An example of the format for the Authorization header is as follows:

Authorization: Basic d3d3Lm15LXN0b3JlLmNvbXw1RDJCNEM1RS1EOEIzLTQ0ODgtOTA0RC02NDA5NDc2MkUxMzY=

The value you see after the word “Basic” is a Base64 encoded string that consists of a username and password separated by a pipe character (username|password), as described below:

Username This is the domain name for the store whose data will be retrieved during the request (i.e. www.my-store.com).
Password This is the API key for the domain, as found in the ZNodeDomain table in the Multifront database (i.e. 5D2B4C5E-D8B3-4488-904D-64094762E136).

Any client of the Znode API must concatenate the domain name (username ) with the domain key (password), separated by a pipe, and then Base64 encode that string to pass along in the Authorization header.

When a request is made to an endpoint, the Znode API will look for the Authorization header and try to decode it. It will then split the decoded string into the domain name (username) and domain key (password), verify that they are a match, then process the request.

If the Authorization header isn’t in the request or if either the domain name (username) or domain key (password) are empty, the API request will fail with the following information:

HTTP status code 403 Forbidden
HTTP status description Domain name and key are either incorrect or missing from the request Authorization header.

Disabling Authentication

Authentication can be disabled by setting ValidateAuthHeader to false in the <appSettings> section of the API’s web.config file. However, in most cases, this value should be set to true in production environments.

<add key="ValidateAuthHeader" value="true" />

During Development

When developing a client that uses the Znode API, it will be useful at times to open endpoints in a browser in order to see data. To ensure this is possible, you need to add an entry in the ZNodeDomain table for the domain of the API itself. In this case, simply disabling authentication will have no effect.

For example, if you have the API deployed locally at “api.localhost.com”, you should add an entry in the ZNodeDomain table where the DomainName field is “api.localhost.com” with the relevant portal ID. This will be the context for retrieving data when viewing endpoints in a browser.

IMPORTANT: This should be for development purposes only.


The requirement to run under HTTPS is specific to your requirements and infrastructure; therefore, the Znode API doesn’t force you to use HTTPS to run it. However, we strongly recommend it, especially for production environments. During development, it would be beneficial to create and install a local SSL certificate in order to properly mimic all calls to the Znode API.


API Series: Cache Refresh

We’ve talked before of the power and flexibility of the Znode API caching layer, but there’s a recent addition to our API that you might find useful – the cache refresh parameter. This little baby is very useful in scenarios where you want to refresh the cache for an endpoint *before* it’s scheduled to refresh on its own.

For example, let’s say you are caching individual products for 15 minutes, which means your cache.config file would look like this:

    <cache enabled="true">
            <route template="products/{productId}" enabled="true" sliding="true" duration="900" />

If you need to dump the cache for product with ID 302 before its 15 minute cache duration is completed, then you can use the cache refresh parameter, like so:

GET /products/302?cache=refresh

This will remove the product from cache, retrieve it again from the database, then put it back into the cache for the next call. Simple but effective.