The Definition of Ecommerce APIs
APIs are critical to headless commerce, but how do you define an ecommerce API, exactly? At a high level, it may help to understand what an API is before we narrow down on what an ecommerce API is. The official definition of API: "An application program interface (API) is a set of routines, protocols, and tools for building software applications. Basically, an API specifies how software components should interact. Additionally, APIs are used when programming graphical user interface (GUI) components." (Source: Webopedia) Put simply, an API declares an interface for you to interact with its logic without you having to know what is happening under the hood, masking the complexity and making it easy to consume and use. What is an ecommerce API? Ok, we defined an API at a high level but let’s dive into what an “ecommerce API” is. An ecommerce API is a collection of ecommerce functionality exposed via API, fairly straight forward. To break down the specific ecommerce functionality this includes at the very minimum, cart, checkout, payments and orders - or in other words a way to transact. One point of confusion that we sometimes hear is that a payment gateway is a commerce API, when in reality these providers offer a single service, namely a payments API, ecommerce is a broader journey comprised or more steps. In headless commerce architecture, ecommerce APIs act as the connecting tissue between the frontend (head) and backend (body). Why use an ecommerce API? An API is the ideal delivery mechanism for ecommerce because ecommerce logic and functionality can be inherently complex. This creates a natural split between your frontend and backend operations and the underlying commerce engine. This turns ordinary developers into super-charged developers thanks to increased efficiencies and productivity. No longer do you need an expensive full stack or proprietary ecommerce platform developer. This allows you to deploy new commerce solutions and get to market faster whilst enjoying access to a wider developer talent pool. Evaluating an ecommerce API It's important to remember that not all commerce APIs are created equal. Below you’ll find some key areas to consider and explore when you come to evaluating an ecommerce API that will fit your business and/or project requirements. Commerce API Types First, it is best to understand what type of commerce API you are evaluating or looking for, the industry standard options today are REST and GraphQL APIs. Both have their pros and cons which would make for another post entirely. In short there is no right or wrong answer. Each type of API is useful for different situations and can even be used in parallel. For a further and more general analysis of the differences between the types of APIs including GraphQL and REST we recommend checking out these great resources: GraphQL and Cortex: What's the difference and why it matters Not all commerce APIs are created equal and why you should care Location & response times Whether this be for legal, security, or compliance reasons the location of the ecommerce API and its databases is something else you will likely need to consider. While edge caching can certainly ensure your content and data is located close to your end customers, the types of data that can be pushed to the edge can be limited for ecommerce use cases and data and only really works for GET requests (retrieving data). When it comes down to commerce logic and interactions (e.g. the critical purchase path through cart and checkout) this cannot be cached. If an ecommerce API is located halfway around the world this can impact latency, your applications performance and ultimately the conversion rate of your store. Milliseconds Matter You’ll ideally want to ensure the location of your ecommerce API is within or close to the location of your customers and the response rates are below 200-300ms for the most part, although there are some exceptions for more complex queries. API-first or API bolt-on There is another key difference to be aware of when evaluating ecommerce APIs and that is to go back to understand how the API first came to be. Many traditional ecommerce platforms did not start out with an API and instead built APIs as a bolt-on to their core platform, primarily to enable an ecosystem of third-party integrations. This key difference affects the feature/functionality coverage area of the API in terms of what is available and also how the API fundamentally works as it has to interact with this more closed, restrictive platform core. On the other hand, API-first means exactly that, the entire product has been designed from the ground up to be consumed via APIs. This leads to 100% (or close to) coverage in feature functionality. We usually find that those that adopt an API-first ecommerce service implement their projects far faster than with a solution that uses bolt-on APIs, as there is less work arounds and hacks required to achieve your desired results. Feature / functionality So, we mentioned in the definition that a commerce API is comprised of a few core elements, products, carts, checkout, payments and orders. Outside of this core functionality there are multiple other services that you may need to call upon. Sometimes these may exist inside the ecommerce API itself. A drawback here is that this feature/functionality might be tightly woven into the core services meaning you'll be back to hacky work arounds when you’re looking to branch out to other best-in-class providers or writing your own logic. Feature functionality (or the lack of) leads onto the next and arguably one of the most important things to consider when evaluating an ecommerce API. Developer Experience & Documentation Quality The quality of the developer experience is another important factor to consider as a poor experience can negatively impact your time to market, significantly increase maintenance and ultimately development cost. A few key considerations you should explore and questions you should ask when it comes to the developer experience include: Is the ecommerce API consistent, standardized and human read-able to requests and response objects across all endpoints or is each API endpoint different and require its own learning curve? i.e. Can a developer read the documentation in a couple of minutes for one endpoint and re-use that knowledge across all API endpoints? Has the ecommerce logic and complexity been well abstracted or are there multiple endpoints and features spread across multiple requests? i.e. Does it take several API requests to process an action that could be handled in a single request? Having to make several roundtrip calls can slow down implementation and your web applications performance. Are there examples and SDKs in your language available and supporting high quality accurate documentation to help you onboard quickly? How easy is it to navigate and browse the documentation to find answers to your questions? Is there a change log and status page? Knowing when something has changed or when services encounter issues is critical to the smooth operation of your business. Is there a community forum or ticket-based support system for questions, best practice advises or for when things go wrong? All of the above questions outlined above around the developer experience will directly impact implementation time of your commerce API and ultimately the development cost. In other words, a positive developer experience will lead to faster implementation times and lower costs whereas a negative or sub-par developer experience will lead to longer implementation cycles and higher costs. Conclusion As you can see, when it comes to understanding what an ecommerce API is and how to evaluate what makes a great ecommerce API there are many things to consider. This article is in no way an exhaustive list and is simply some of the top areas you should consider when evaluating an ecommerce API. If you would like to learn more about ecommerce APIs, check out the 10 Ways Ecommerce APIs Can Lead to Developer Nirvana We've also answered frequently asked questions about headless commerce.