strawberry rhubarb pie cooling on a rack
PHOTO: Laurence Hart

I’ve been making and eating a lot of pies lately. Fresh fruit is readily available and my pies reflect the seasons. I spent spring perfecting my strawberry rhubarb pie on some very willing guinea pigs. With the advent of summer, fresh peaches are arriving, meaning it's time to enjoy my favorite pie and its distinct mix of crust, filling and topping.

At work, I am designing a system with three layers, mirroring the pies I make. Instead of crust, I have a flexible, multi-dimensioned content model to provide structure. The API layer serves as the filling, defining the content services being delivered. Topping the system off, is the user experience, which we mapped out to maximize the ease-of-use. Just like when making a pie, these three components must work in harmony while still following their own set of rules.

Building a Foundation: The Content Model

Making a good crust is the most important skill when making a pie. It has to hold together, be flaky and complement the rest of the pie. A generic crust from the store can serve as the foundation, but it ruins the creativity poured into the rest of the pie.

Similarly, the content model is the critical foundation of any content services application. It represents the different business entities, all the content belonging to each entity, and the relationships between them. It allows for information to be properly stored, retained, searched and retrieved in their proper business context. When done right, you are able to understand and manage the content across multiple systems. 

While both the logical and physical layers of the content model will share some common design elements, all good models must reflect the organization’s business. Entities, and their relationships, vary by importance and in what is tracked.

  • Are the objects related?
  • Parent-child or peer relationship?
  • Do business rules flow along the relationships?

These are only a few of the questions you'll need to answer when you think about the model. Once you have it roughed out enough so that it reflects how the organization works, you are ready to start on the filling.

Related Article: Content Modeling: What It Is and How to Get Started

Tying it Together: The Content Service APIs

Now we get to the heart of it all. Just like pie filling, the API is the core of what is being delivered by the content services application. Projects are defined by the services they deliver.

Like pie filling, API design follows some core basic rules but there is a lot more leeway for personal flair. How they are implemented depends on taste. Do you want to make the content services granular, generic or somewhere in-between? The answer to that question is driven by two factors.

The first is the content model. The content services should interact directly with the entities in the content model while respecting their relationships. This includes the individual pieces of content and the different business entities to which they belong. The model and the API work together to deliver a well-meshed experience.

The second factor is how people will consume the content services. While everything may be modeled by case, developers may want to access items by very specific case types. Where it may not make sense to have different types of entities in the model, it may make it easier for consumers of the services to have distinct services for each case. This allows for people to use the each service for a specific business use case without making the model unnecessarily complex. When done correctly, this approach does not create undue complexity. Several business-focused content services may only differ underneath by a simple qualifier when interacting with the model.

Related Article: Content Services Threaten to Repeat the Mistakes of Our ECM Past

The Visual Appeal: The User Experience

The user experience is the most critical element in any application. When you think of pie, the first thing you see is the top. Pie tops must be visually appealing and functional. Lattice tops are pretty. But they also prevent the pie from exploding while being baked and allow for the sweet smell to permeate the house. You can decorate the top, but don’t make it hard to cut slices. Knives don’t like cutting through those decorative pecans.

The user experience is how users will judge the content services and front-end development.

  • Is the resulting system faster than the old one?
  • Can people easily tag information to find later?
  • How many tabs, windows or screens do they have to switch between to get their job done?

The content services and other APIs that pull additional information from external systems need to support all of the elements of the user experience. The result has to be seamless to people so they feel they are consuming a single, useful application.

Related Article: User Experience Debt Is Sapping Our Productivity

Who's Ready for Pie?

At this point, you are likely craving a good pie. I know I am. You also hopefully have a better understanding of the importance of the three tiers in a content services application. These distinct tiers will likely run on different technologies. And just as you sometimes might mix in a few raspberries with the peaches, you may choose to have multiple technologies delivering different tiers.

One critical difference separates pies from content services applications: Pie needs to be made from scratch to deliver quality. When building content services applications, start with solid components and modify them as needed to create the recipe for your success.