In a physical store, a human walks around interfacing with a customer moving from displayed merchandise to the cash register. He/she knows what to do. In a digital store that human is a packet of information that moves around from one event to another advancing the purchase cycle. That “human” is a RESTful API call.

REST (REpresentational State Transfer) API (Application Programming Interface) is an architectural style for developing web services. REST is simple as it builds upon existing systems and features of the internet’s HTTP framework in order to achieve its objectives, as opposed to creating new standards, frameworks, and technologies. A RESTful APIs take advantage of HTTP methodologies. They use GET to retrieve a resource; PUT to change the state of or update a resource, which can be an object, file or block; POST to create that resource, and DELETE to remove it. This is a lightweight mechanism compared to an earlier protocol called SOAP (Simple Object Access Protocol) that used XML messages over HTTP.

A website’s pages (like rooms in a store) serve different purposes – a landing page to welcome a visitor, one that displays categories, yet others that have product listings and checkout. The composition of all these pages are done on a server in the back, or at least that was the case in traditional design architectures.

Every major e-commerce platform has the API defined to expose the object model of the application.

When SAP Cloud Commerce shipped its Omnichannel Commerce Connect (OCC) API it offered the following features:

• Catalog data:Catalog data can be exposed fully or incrementally using the catalog API, allowing external systems, such as mobile devices or CMS, to create navigation and content structures.
• Search and navigation:SOLR based search and navigation API provided search results along with the facet query strings. The refinement path from each search response can also be used for client-side integration.
• Customer Module:Customer registration could be done using an API in this module. Additional features like address management were also part of this module.
• Product information:Detailed product information, including URLs to images and detailed descriptions, are exposed via the API. The client can request information about promotions, product reviews, etc. and can refine the information using a range of parameters.
• Cart and Checkout functionality:Once a shopping session is started, the API can manage a user’s cart, including adding items, changing quantities, or removing items from the cart. The API can also manage delivery addresses, retrieve and set delivery modes, and add customer payment information.
• Orders:Once an order has been placed, the orders API gives clients access to list and detail views of all orders placed.

Magento 2 also has a rich set of RESTful API defined on all modules and allows for extending the API to include custom modules.

These features mimic the commerce website and most native mobile apps stuck to the same story. The improvements were in the rendering, caching of API data locally and with additional features like store locator.

Side by Side and Headless Commerce

Let us say, you walk into a swanky store, walk into a beautiful glass room, sit on a sofa and items are brought to you to view and pick from. When you are ready to buy to get up and go to another room, which lets you in (let us call this “single sign-on”, and in that second room there is a cash register which lets you pay for the items. This is side-by-side commerce because of the adjacency of the rooms where you browse items(CMS) and the room where you buy (E-commerce).

Now let us say, you walk into a store, sit on a sofa and items are brought to you to view and pick from. When you are ready to buy a salesperson brings a cash register to you and you check out right there on the sofa. This is headless commerce because you never leave the “glass room” – you are served up all the content by the CMS and the check out by the e-commerce utility.

The sales person running around serving you is the RESTful API call interfacing between the utilities offered by the two rooms (CMS and E-commerce).

With the availability of APIs, a loosely coupled architecture emerged. A platform could handle all the core commerce functionality and offer no UI. The UI could be provided by a separate CMS or an IoT device or any other appliance or innovation.

Separating out the core commerce functionality from the front-ending devices and applications offers the following benefits.

Separation of Concerns: One of the big issues in the e-commerce industry is how does one separate the “beauty” and the “beast” – the beauty being the marketing and user experience and the beast being the hard business logic that forms the core of e-commerce. Headless architecture allows solution experts to design solutions based on the separation of these two worlds or concerns. In a traditional approach, a commerce platform would have to handle the features of marketing and user experience – something it is not really designed to do. In the analogy of the swanky store we have used the cash register is not built to be a shopping display window and vice versa. In the headless approach, non-commerce functionalities are offloaded to specialized applications created for that purpose (such as a CMS for content browsing or product education).

Flexible front-end: Businesses where the marketing team needs all the flexibility of a high-end CMS like say Adobe’s Experience Manager (AEM), headless commerce makes it easy to integrate a marketing-centric UI to the commerce functionality.

Omnichannel: Device specific front end interfaces could be created without rearchitecting the commerce services.

Flexibility in Delivery: Parts of the system could be delivered without impacting the core commerce functionality.When is Headless a good way to go?

If you have legacy apps that cannot all be retired at the same time, Headless is a good way to go. You can build a solid customer experience layer and switch out back end systems as they are retired without affecting the CX layer in a material way.

An “all-stack” (picking many modules/suites from one vendor) approaches is workable when you adopt a “big bang” replacement strategy. Challenges with API Based Commerce

Though headless commerce is an improvement over the monolithic approach, the design of the API and the delivery of data continues to follow the old model. The flexibility to design a better user experience independent of the commerce engine is not easily used as the API designs follow the old model. To create an alternate user experience, either new APIs are to be created or multiple-round trips to the server are to be done to compose a page. If the front end needs lesser data, lightweight APIs are to be created.

Here are some examples of the issues in using RESTful API.

The product details page (PDP) must show related products.

For this functionality, multiple API calls are to be made as follows.

• Query the server for the product details. Product details API must include related product ids.
• Make one or more calls to fetch the related products based on the ids returned in the earlier call.

The first call is supposed to return the full details while the second call is expected to return bare minimum information like product title, small image URL, its prices. So, even such a small functionality of displaying products we might need two versions of API for products (with possibly multiple calls) – one that returns the full details, including related products and another to return minimal data.

A dashboard like page for My AccountThe traditional My Account page lets the users manage their addresses, newsletter subscriptions, view order status or raise requests. If this has to be presented in the dashboard-like page with multiple components for each part, the client has to make multiple calls to the server to fetch the details as the page deals with different types of entities.

• Fetch customer information with addresses that constitute the basic customer profile.
• Fetch recent orders with limited information like order placed date, its status and the value of the order.
• Fetch newsletter subscriptions, which happens to be part of the marketing profile of the customer.

The solution to address this is either to have the client application live with multiple round trips to the server or develop fresh API that returns the desired data from the server. Such a custom developed API ends up getting tightly coupled with the UI that uses it.Summary

Headless commerce has its advantages. But to harness the full power of headless commerce architecture, extensive custom API may have to be written for better client-side performance. This holds good especially for UI designs targeting quality user experience. This adds to the development effort where headless commerce is a priority.

The advent of GraphQL

For a Facebook-like interface, traditional RESTful API won’t suffice. To address the need to support complex UI, Facebook developed GraphQL in 2012 and released it for public access in 2015.

GraphQL provides an efficient, powerful and flexible approach to developing web APIs. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server, therefore preventing excessively large amounts of data from being returned. The flexibility and richness of the query language also add complexity that may not be worthwhile for simple APIs.GraphQL and Commerce Platforms

The scenarios shown as examples in the previous section can be addressed gracefully with GraphQL.

To explain with the store-salesperson analogy, when the customer requests multiple items from the store that are related to each other, say, a razor along with blades and shaving, the REST employee would provide each of the products separately but the GraphQL employee could provide all these in one go.

The user interface can be flexible to show items together based on the relationship. We can have the client make just one call to fetch relevant data to render the UI. But that is just one part of the story. The call would in turn query the underlying platform.

The standard RESTful way of execution is as given below.

With GraphQL, the execution would change as given below.

Challenges Database QueriesA layer for executing GraphQL queries to fetch data from the underlying systems needs to be worked out. Since the query is close to the data model, the data access parts have to be extended to fetch only relevant content. This could be a major redesign for the platforms. A short term solution would be to retain the data retrieval as is and use it to compose the response for the GraphQL queries.

CachingSince a GraphQL query response can contain nested objects, caching of the entire response is prone to have stale data. While this may be an acceptable issue for Facebook like applications, e-commerce applications should not show inconsistent information. A clean caching strategy needs to be defined.

Scope of GraphQLIt could be a major architectural change to support GraphQL for e-commerce systems. But as far as e-commerce is concerned, the benefits of GraphQL may be limited to a few pages. Magento came up with its GraphQL Schema for a few entities. This set is useful for a starter. This may not fully eliminate the multiple API calls we saw in the examples. But having the support for GraphQL in the platform can help developers use to extend the schema to produce more optimized queries for creative buying experience.