Znode Multifront

API Series: All JSON, All The Time

In the previous post about our API we talked about why we decided on REST, and this post is about another decision point in API design: what format should you use for the data? In today’s world this means supporting XML or JSON or both, which is something that can spark a bit of a holy war with some people, and admittedly we had much internal discussion about this as well. But in the end we decided to support JSON only in our API.

XML Web Services

Historically, APIs and web services have centered around XML, and rightfully so. It’s a well-known standard and understood format, and is a huge reason why APIs and web services have become so prevalent over the last 15 years. Enterprise tools and software packages were created to generate and consume large amounts of XML being passed around the web, opening doors into external services that weren’t there before.

And while XML has played such an important role in the web service landscape, it’s not without its faults. It’s heavy and tends to be tool-centric, so much so that different tools have different ways to generate and parse XML data, sometimes causing inconsistencies that make it difficult to work with.


But these last few years have seen web developers get back to their HTTP roots. They started asking themselves, “Why do I need a tool to handle all this XML when I can simplify the data and leverage HTTP to process it?”. This lead developers to embrace JSON and REST, a data format and an approach that gets developers back to the heart of web itself. Plus, there isn’t a single tool or software package out there that understands XML but not JSON. JSON is as ubiquitous now as XML has always been, which has helped increase its adoption.

No Angle Brackets

For us, early in the development cycle for the API, we experienced our own issues when trying to support both XML and JSON. Exposing and consuming JSON data from our API turned out to be easier, more flexible, and a better overall experience than XML. And if supporting XML was frustrating for us, the creators of the API, then what would be it like for our customers and partners?

Ultimately, JSON accomplishes the same things as XML, is much lighter in terms of data payloads, and simply gives consumers of an API a better development experience. This is why you won’t find a single angle bracket in our API. It’s all JSON, all the time.


API Series: Why REST?

When building a new API there are numerous decisions you’ll have to make along the way, but you could argue that none are more critical than the type of API you want to create. You have to take into consideration what kind of clients will consume the API, their technology stack, how they will connect to the API, and what the API will be used for. In the .NET world, this typically leads you to three choices: ASMX, WCF, and REST.

With ASMX and WCF, you’re basically forcing clients of your API to be .NET specific. That no doubt works for many people, and with us being a .NET ecommerce platform we certainly could have taken the same approach. However, we didn’t want to handcuff anybody to a single technology. Just because we chose to implement our API using .NET shouldn’t mean that consumers of the API must be .NET as well. Seems kind of silly and limiting.

The single biggest reason we chose REST for our API is because it’s technology-agnostic.

REST is built on the fundamentals of HTTP, so any web technology can use it. Ruby, PHP, .NET, Java, Python, whatever. It doesn’t really matter, and that was extremely important for us as we move forward as an ecommerce platform. We want as many people consuming our API as possible, and implementing the API in REST allows this to happen.


API Series: Guiding Tenets of the API

When we first started design discussions for version 2.0 of the Znode API, we talked about all kinds of things. What should the URLs look like? What technology should we use to build it? Should we support both JSON and XML or just one or the other? If based on REST, how far do we take it? How do we make the endpoints flexible enough to support robust querying and filtering? We asked ourselves all kinds of questions, and in doing so we came up with a few tenets that guided our approach to the overall design and implementation of the API.

Tenet #1: Easy to Consume

Our primary driving tenet with the API is that, above all else, it must be easy to consume. To put this in perspective, think about two other well-known APIs: PayPal and Stripe. PayPal’s API is historically bad and hard to use due to poor documentation and inconsistent design. Stripe is at the other end of the spectrum and has a really nice API with good documentation, sample data, and a design that is consistent from one call to the next.

We wanted our API to be on the side of the spectrum that Stripe is on, and in fact, we used Stripe’s API as part of our design inspiration. And we think we’ve succeeded. All of our endpoints are completely consistent across the board, and we provide thorough documentation and sample data at every step along the way. We took the guesswork out of using our API, and all of this together makes for an API that is easy to understand and use.

Tenet #2: Predictable

The second tenet of our API design was that it must be predictable in nature, and this is a direct correlation to a consistent design. Specifically, this means that the behavior exhibited for every endpoint should be the same.

For example, every time you make a successful GET request to retrieve data, you will not only receive the expected data, but you are also ensured to get back an HTTP status code of 200. Similarly, when you POST data to an endpoint to create a resource (such as adding a new product), if successful you will not only receive back the newly created resource, but also a 201 status code and a location header with the URL for where the newly created resource exists.

Predictability is an important aspect in any API, and the Znode API has it in spades.

Tenet #3: Discoverable

Another tenet of our API is that every aspect should be discoverable, and in the Znode API this comes down to two things: 1) the built-in help docs and 2) being able to open endpoints in the browser. Let’s start with our API documentation.

The Znode API help is built directly into the API itself. There is no Word document or PDF that you have to read through to know how to use the API. The API is a living, breathing thing 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).

Being able to open endpoints in the browser was also important because it allows you to “see” and “touch” the API with your own eyes. You can easily open any endpoint URL in a browser and play around with its options – expands, filters, sorting, paging – and see the data that gets returned. This goes a long way toward providing consumers of the API a high comfort level.

Tenet #4: Wide Open

Finally, the last tenet of the API is that it needed to be completely open. In other words, we didn’t want to hide any data. The reason for this is because the API serves two purposes: it’s used to build frontends for applications and it’s used for integrating with other back office systems.

We also understand that we don’t know exactly how every customer will use the API and the underlying platform. Every customer’s business is different and it would be ill-advised of us to try and determine how the API should be used. It was created to provide the biggest extension point of the Multifront platform, and that couldn’t happen if we limited it in some ways. So we left it wide open and we’re excited to see what people build with it.


Tips To Cheat Your Way To Endless Lives On Candy Crush

This 30-second technique could save yourself/ruin your daily life.

As any Candy Crush addict understands, there’s nothing mo Re depressing that returning up from the countdown of disaster.

Fear not. There’s another manner. All you have to do is follow these three easy steps…

You have lost all of your lives. Again. And you have got to wait almost 20 minutes before it is possible to have another proceed. Yes, you could join using Facebook, at which point you can plead friends and family for lives. But no one wishes to acknowledge how far down the Sweet gap they have dropped.

Measure 1: Go to your own telephone number/tablet’s settings and turn the substitute for automatically set the time and date OFF.

Step 3: Move right back into Candy Crush.. BINGO! The countdown has disappeared and you once more possess a full complement of lives.

Measure 2: Every time you use up all your lives, move the date forward with a day.

It is about to get a LOT worse in the event you believed your addiction was bad before.

Note: Transferring the day and time forwards may possibly quit your iMessage, Fb, Facebook or other apps from working correctly.

When you want to play, to avoid this issue, when you’ve finished enjoying Candy Crush simple get back the date and time to the correct options, then, only move them forwards again. Good fortune!

But remember, most of the lives on earth will not help the fact that you’ve been stuck around the same amount for six weeks.


API Series: Introducing the Znode API 2.0

Last week we announced the release of Multifront 7.1, the latest version of our .NET ecommerce platform, which continues to improve the overall experience for our customers. Multifront 7.1 includes a number of important enhancements and additions, such as multiple ship-to addresses, customer-based pricing, and an improved internal provider engine. But the most significant item in Multifront 7.1 is our new API. In fact, it’s so important, it gets it’s own version number: 2.0.

Overhauled for the Long Haul

Version 2.0 of the API has been overhauled from the ground up and redesigned with the future in mind. It’s a completely open set of REST endpoints from which nearly anything can be built on top of the Multifront ecommerce platform. From the shopping cart checkout process to creating administrative reports, it includes rich querying and filtering capabilities that allow you to request as much or as little data as you need.

A Shift In Thinking

This new API represents a shift in our overall platform architecture as it now becomes the key piece in almost everything we do. From building user interfaces and applications to integrating with various back office systems, the API is being positioned as the central figurehead that makes everything go within, and outside of, the Multifront ecommerce platform.

Why Is It So Important?

There are three reasons why the API is as important as we’re making it out to be:

  1. The Headless Engine – We’ll talk more about the headless engine in a later post, but it’s really about being able to build any type of UI on top of the API. External web sites, desktop apps, mobile apps, whatever.
  2. Integration – Naturally you can’t talk about an API without talking about integration, and our API is no different. The Znode API 2.0 allows for integration with any kind of system in your infrastructure.
  3. Extensibility – The API serves as the outer boundary of Multifront, and can be used to extend our ecommerce platform any way you see fit.

Technical Highlights

For the developers out there, here are a few technical highlights of the API 2.0:

  • Built Using ASP.NET Web API – This provided a lot of the heavy lifting for us, allowing us to focus on our endpoint design instead of lower-level concerns.
  • 100% RESTful Endpoints – When we say 100% RESTful, we mean it. We spent more time going through the actual HTTP specification than we care to admit.
  • Supports JSON Format Only – You won’t find any angle brackets in our API as XML is not supported. It’s all JSON all the time.
  • Built-in Caching System – The API has its own caching layer that you can tune to meet your exact requirements.
  • Built-in Help and Documentation – Part of the ASP.NET Web API, we customized and extended it to make it easy for developers to get up to speed quickly.

See It In Action

All this talk about our awesome new API sounds great, but how about we show you instead? Head on over to api.znode.com and start clicking around. In particular, click on the “API” link in the top-right corner of the page so you can see all of the endpoints which are currently exposed.

More to Come

We’re thrilled with how the API 2.0 turned out, and we’ve got plenty more to say about it. In fact, this post was just the introduction in a series of upcoming posts about what’s in the API and how it was made. Some upcoming topics include:

  • HTTP Verbs and Status Codes
  • Expands and Filters
  • Sorting and Paging
  • Help and Documentation
  • Models and Responses
  • Caching
  • And more…

Stay tuned.