API Series: Expands and Filters

Any API is really all about one thing: data. An API needs to accept data, do something with it, then give data back. For the consumer of an API, what happens in that middle part doesn’t matter. All they care about is that they sent the API some data to work with and the API returned data to them in a format they expect. And a big part of data for an API is being able to support rich querying capabilities so that the client gets back exactly what they need. For the Znode API, this is handled by expands and filters.

Expands

The concept of expands is nothing new in API design, as many APIs support them, and even our own implementation is loosely based on the OData specification for expands. In short, expands is a way of asking for related data during the same request. For example, when retrieving a product, you might also want to get its customer reviews and any categories it belongs to. Without expands, you might have to do this in three separate calls, perhaps something like this:

GET /products/123 GET /products/123/reviews GET /products/123/categories

But with expands, you can consolidate those three calls into one, like so:

GET /products/123?expand=reviews,categories

You can chain as many expands together as you need, simply use a comma to separate them (a configurable option we’ll cover in a later post). And that’s the big benefit of expands – to eliminate extraneous API calls that you can otherwise handle with one call.

Filters

Similar to expands, filters were also roughly based on their OData specification. Using filters allow you to retrieve only the data that satisfies an expression; think of filters as the WHERE clause in a SQL statement. For example, you might want to retrieve a list of products that have a retail price greater than $5.00. With filters, the URL request would look like this:

GET /products?filter=retailprice~gt~5.00

Also like expands, you can chain filters together. For example, you want to retrieve a list of products that have a retail price greater than $5.00, but only for products whose name starts with the letter A. The request for that would look like this:

GET /products?filter=retailprice~gt~5.00,name~sw~A

Filter expressions are basically tuples that consist of the following format:

key~operator~value

The tilde character (~) is used as the default separator between key/operator/value, while the comma is used to separate multiple filter expressions (both of which are configurable). Below is the list of currently supported filter operators:

Operator Description Example
eq Equal to GET /products?filter=name~eq~apple
ne Not equal to GET /products?filter=name~ne~apple
cn Contains GET /products?filter=name~cn~pea
gt Greater than GET /products?filter=retailprice~gt~4.99
ge Greater than or equal to GET /products?filter=retailprice~ge~5.00
lt Less than GET /products?filter=retailprice~lt~5.00
le Less than or equal to GET /products?filter=retailprice~le~4.99
sw Starts with GET /products?filter=name~sw~app
ew Ends with GET /products?filter=name~ew~pple

Filters in the Znode API can also be used to query for nullable items by using a “null” value for the eq (equal to) and ne (not equal to) operators, as such:

GET /products?filter=externalid~eq~null GET /products?filter=externalid~ne~null

Powerful and Flexible

When it comes to querying data from an API, expands and filters are important because it gives clients great power and flexibility for how they want to retrieve data, and the Znode API has very robust expand and filter capabilities.

A Unified Experience for Content and eCommerce

In today’s world, there are two things that drive the continued growth of the Internet: content and eCommerce. The phrase “content is king” has never been truer; after all, people find you online with great content that ranks well in the major search engines. But if content is king, then eCommerce sits by his side as the queen. However, the union between King Content and Queen eCommerce isn’t always rosy. For many websites, a big problem in the content-eCommerce relationship is that managing content and managing eCommerce is a vastly different experience.

Data This, Data That

Think about the data for content. Items such as titles, headlines, content bodies, section headers, authors, and revisions are just some of the common components. Contrast that with eCommerce data where products, catalogs, prices, SKUs, gift cards, promotions, payments, shipping, billing, orders, and taxes are at the forefront. With the data sets being so different between content and eCommerce, products built around managing that data do so from different points of view. Content management systems are all about writing large amounts of text, while eCommerce systems take a more spreadsheet-like approach (albeit a very complex spreadsheet). Because of this, rarely will you find a platform that handles both equally well, which is why there are separate market segments for content management systems and eCommerce systems.

Experience Is Everything

What this is really all about is the entire user experience. The nature of their data dictates that the experience for managing content is different from the experience for managing eCommerce. For many companies, this also means additional personnel and training. And that translates to more cost. But does it always have to be that way? Can the two be brought together in a seamless, unified experience?

Hard At Work

At Znode, that’s a question we’ve been working hard to answer for most of this year. We know that content and eCommerce go hand-in-hand, and with Sitecore being the clear leader in the .NET enterprise CMS space, we set out to provide a solution that makes people feel at home managing eCommerce data in the Sitecore environment. Native integration with an eCommerce platform is the one piece Sitecore has been missing – until now. The Znode Commerce Engine for Sitecore fills this gap with a completely integrated solution that unifies Sitecore’s Customer Engagement Platform with Znode’s Multifront eCommerce platform. The experience between managing content and managing eCommerce in Sitecore is now the same.

True Integration

We’re not throwing around the words “integration” and “unified” loosely, as we aren’t simply talking about embedded iframes within Sitecore. We’re talking about Sitecore users and developers feeling at home in the environment that they’re used to working in. As the Znode Commerce Engine for Sitecore was developed, keeping a consistent and expected Sitecore user experience was paramount to its overall design. If something felt too “non-Sitecore”, then it was reworked until it had that at-home feel. The result is a deep integration between the Sitecore CEP and Znode Multifront that gives users a seamless workflow for managing their content and eCommerce catalog.

The API Is Where It’s At

The key to this tight integration is the Znode API. The Znode API is an extremely robust RESTful set of services that allows you to integrate the Znode Multifront platform with nearly any application. The Znode API exposes all data and functionality required to build a highly scalable eCommerce solution, in this case, the Znode Commerce Engine for Sitecore.

Data Flow Made Easy

The component in the Znode Commerce Engine for Sitecore that utilizes the Znode API is the Znode Data Connector, which allows you to easily map and translate data between the Sitecore CEP and Znode Multifront. The connector can even be extended to map data from other back office systems, thus making overall integration even better.

Just the Beginning

And we’re just getting started. As good as the Znode Commerce Engine for Sitecore is now, there are big plans in the works to continue to raise the bar when it comes to managing content and eCommerce together. Like we said, the experience is everything, and we’re working closely with Sitecore to ensure users and developers continue to get the unified experience they deserve. For a brief demonstration on data importing and mapping for the Znode/Sitecore connector, watch the Multifront Sitecore Connector Overview video. To learn more about the Znode/Sitecore unified content and eCommerce experience, download the Enterprise eCommerce Integration for the Sitecore CEP Platform Infographic.

Photo by Sean MacEntee