Sajjad HeydariThe terms REST API and API are thrown around a lot when talking about headless commerce, but what do they really mean? In this post we'll look at APIs and REST APIs, what they are, and what makes them useful. We'll do this in a way that's easy for e-commerce marketers to understand.
APIs
Applications need to communicate with each other to integrate or extend one another. For instance, a checkout service needs to communicate with a marketing automation service to send cart abandonment emails.
Applications often talk with one another by sending 0s and 1s to each other (i.e. binary code), but that makes the talking protocol extremely hard to develop and maintain. So instead of writing a different talking protocol every time, we use an Application Programming Interface, or API.
The API defines an abstraction that makes it easier for programmers to develop and maintain, like programmers working at a retail company who are responsible for developing and maintaining a headless commerce stack that relies heavily on APIs.
REST APIs
REST stands for REpresentational State Transfer. It is a group of APIs that are defined over the HTTP protocol, meaning the underlying software doesn't have to be on the same computer since HTTP is globally understood across the Internet. REST APIs are the standard in web and mobile development, with hundreds of libraries and tools that make the development process smoother.
REST APIs and APIs in general allow software to rely on each other. Do you have e-commerce software that powers your online store and want it to talk to users on Twitter as part of an omnichannel sales strategy? Well, Twitter has a REST API and the commerce software in your tech stack should too. Or what if you have an online store and want to develop a mobile app? If your online store relies on a headless CMS, it already has an API that you can use for the mobile app.
A headless CMS is an integral part of headless commerce. It is a unified API that lets you send your content and products to users wherever they are—your website, mobile app, or wearable device. This creates a better, more seamless brand experience in comparison to having parallel communication channels that are unaware of each other.
Technical Overview
REST API relies on performing HTTP actions such as GET, POST, PUT, DELETE over a path, such as /users/ or /orders/1812. They have a host, such as api.example.com, and some other parameters like payload and headers that describe the details of the action. In return, they return a JSON, explaining what happened when they ran the action.
For example, let's say I want to see the latest personalized offers delivered by software like our Offers product. I would send a GET request to /offers with a query string ?orderBy='date' with my credentials in the headers. Of course, the naming depends on the software, which is often explained in the documentation. Which brings us to the next point...
Documentation!
Every programmer hates writing API docs, but they are probably the most vital thing. Without proper documentation, the process of utilizing APIs becomes a guessing game. Guess what this field means, guess what type it expects, and guess what the return types are!
These days there are lots of different tools such as GitBook, Swagger, and Postman that help teams properly document different versions of their API and explain expected behavior and calling conventions.
It's common to have the documentation in English along with code examples, so keep an eye out for them. These really help developers—and even marketers who are considering different headless solutions—familiarize themselves with the API and deliver a better, faster product. For example, Fabric API's documentation explains each action with its expected behavior, fields, example request, and example response—with a proper changelog to keep track of the latest updates.
What Makes an API Useful?
Aside from the documentation, certain design choices help make a REST API the proper tool for preventing the headaches of integrating different software. In this part, we're going to take a look at some of the most important aspects of it that concern REST APIs.
Naming Convention
Maybe the most important aspect after the documentation is the naming convention. There is no right or wrong way of doing it, but there are a couple of different things to consider. First of all, the names should be meaningful. You don't want to work with an API that names the paths /foo and /bar. It would be a horror to understand what's happening while developing and debugging it.
A good naming convention has consistency, all of the names have proper meaning in one language (often English), and they are capitalized in the same way. Capitalization has different forms such as camelCase, UpperCase, kebab-case, snake_case, and a few others. Mixing them creates confusion all around. It's also frowned upon having a verb in the path names. For instance, you don't want to have a path /get_offers, you want GET on /offers. Keep an eye out for these kinds of naming conventions.
UX
Yes, UX. The proper API reflects the user experience in its structure somehow. If, for example, you require a method to add a list of items to the shopping cart at once, like for bundled offers, the API should provide it. And if you want to be able to see the offers that are going to expire soon, the API should have that option, too. If, instead, the API gives you GET on a list of all offers and leaves the sorting to you, it will be a slow, long process on the user's device just to see the offers that are going to expire soon.
Response
The response of the API often has a direct impact on the speed in many different ways, the most apparent one being the size of the response. If the server returns a 5mb file every time you are calling it and you want to call it every second, it's probably going to cause some problems. Having a fast API with a small response size is a sure way to decrease page load time, which increases conversion rates for e-commerce. (Often, the servers gzip the response to make it shorter, which is always a plus.)
There is no exact measurement to say that the response is too long; it's application dependent. But as a rule of thumb, keep an eye out for any unnecessary information the API is returning. For example, we might not want to see comments on products when getting a list of the latest deals!
Aside from the JSON, the response also contains a status code and headers. You might recognize the 404 status code, which means the server didn't find what you were looking for. Having proper status codes and headers ensures an easier integration with different toolings, which decreases the development and maintenance cost for any customization.
Versioning
Software always gets updates. APIs change over time. This could happen for any number of reasons such as design flaws, security issues, or even new, previously unseen, functionality. The problematic part is that the old code might stop working if the client is not updated. One possible workaround is to allow the user to select their version of the software; another is to have it reflected in the calling convention. This could be in a header (API_VERSION=2020Sep15), in the path /v1/users or even part of the query string ?api_version=1.2.
The important thing is its existence. Most of the development time is spent in finding the root cause of the problems; having proper versioning reduces this cost drastically. Without proper versioning, things might break upon updating and it would be hard to realize why, increasing the cost of development!
Conclusion
If you're a marketer in e-commerce you should now have enough technical chops to have a high-level conversation with your development team about performance, versioning, and capabilities of the APIs in your tech stack.
Remember: documentation, consistency, predictability, response size, and performance are things you need to look out for when adding new commerce software to your tech stack. As a marketer, it's important to know about these things as they can impact conversions and revenue.
