Elastic Path Commerce for AWS Setup
Core Commerce Architecture
Cortex API Architecture
Tutorials & Code Examples
Elastic Path Production Tools
Core Commerce Release Notes
Cortex API Front-End Documentation
EP for Adobe Marketing Cloud Architecture
EP for AMC Developer Documentation
EP for AMC Release Notes
Cortex Studio
Architecture Overview
Architecture Overview
The Cortex API is a lightweight API that leverages the power of Elastic Path's Commerce Engine to provide e-commerce services for multiple platforms (Mobile, Game Consoles, PC, Connected TV, Microsites, E-commerce Widgets, In-software Purchases, etc). The API is designed so Cortex API client developers can use any programming language (JavaScript, PHP, Java, C#, etc) to quickly create powerful e-commerce applications and run them on any system.
This document covers the Java architecture behind the Cortex API. For more information for how the API's URIs and JSON objects are structured, see API Fundamentals.
Cortex API Design Philosophy
The Cortex API is designed in a multi-layered application structure. Each layer has a specific set of responsibilities and each layer is loosely coupled to the other layers. This design is known as abstraction, where each layer is responsible for a set of tasks and each layer isn't interdependent on the other layers to complete tasks. The sections below outline the Cortex API architecture, including the application container and each of the architectural layers.
The reason why this architecture design was chosen is that it simplifies the job of Java developers who are customizing the Cortex API. Java developers only need to know two layers: the Rest Resources Layer and the Integration Layer. Customizations, including new features and additions to existing features (like an extension for a cart, lineitem, profile, and so on) are coded solely in these two layers. Because the layers are abstracted, Java developers don't need to touch the other layers in order to implement their customization. For example, if the Java developer was adding a new recommendation feature to shopping carts, they would create a new resource in the Rest Resources layer that would add a link to the shopping cart and create a new resource integration in the Integration Layer to integrate with a back-end system. Developers wouldn't have to change the Authentication, HTTP Bridge, or the Kernel layers in order to create this customization—they also wouldn't have to change the shopping cart resource.
Cortex API Architecture
The best way to understand Cortex API is to understand the container it runs in and each Cortex API's architectural layers.
Application Container
Cortex API runs in an OSGi container. This container then runs inside of a web application and the web application runs on an application server. This setup leverages the power of the OSGi component model while allowing Cortex API to run on a standard application server. Since OSGi contains a collection of components (bundles), each of which can each be in a different state, we created the following OSGi bundle to ensure the server returns an error state when any of the required top-level resource bundles are not started:
- resource-configuration bundle - Contains an OSGi blueprint configuration file that defines the list of the top-level resource bundles Cortex API requires to be in a valid working state.
Since Cortex API web application needs to define all of the Maven artifacts to be included for deployment, the web app's pom references the top-level resource bundles as well as all the bundles from the other layers.
Architecture Layers
The sections below provide an overview of each layer and describes their responsibilities. For a detailed description of how a single authorized request makes its way through these architecture layers, see Architecture Call Stack.
The authentication layer is responsible for logging customers into Cortex API and for restricting unauthorized customers from accessing protected resources. Once authenticated, Cortex API passes an OAuth2.0 token back to the client. When a request for a protected resource comes into the authentication layer, the layer checks that the customer's token is valid and then allows the request to proceed. For more information on the authentication workflow, see Authentication Workflow.
The HTTP Bridge uses Jersey to determine the type of incoming HTTP request (GET, PUT, DELETE, POST) and then delegates the requests down to the Kernel for processing. When the request result percolates back up to this layer, the Bridge uses Jackson to convert the returned result into a JSON object. The Bridge then sends the JSON object and an HTTP status messages, indicating the request's success or failure, back to the application that initiated the request.
The Kernel receives the request and the request's URI from the bridge. The Kernel parses the URI to determine the resource being referenced and then delegates the request to the Resource Server to load the resource.
Each resource is a separate OSGi bundle that controls a specific aspect of e-commerce functionality. For example, the profiles resource is responsible for the customer's details, such as first name, last name, and addresses. The carts resource tracks the items you're purchasing along with total quantity, and so on. It is in this layer alone that java developers make their customizations to expand Cortex API capabilities. For more information on resources, including how to create them, see Introduction to Cortex API Resources. For tutorials on expanding Cortex API, see Tutorials.
Integration Layer
This layer is designed in a similar manner as the Rest Resources layer, where each resource integration is a separate OSGi bundle. Each of the bundles in the layer are implementations of the lookup and writer strategy interfaces that are defined in the Rest Resources Layer. The rest resources call into this layer to perform tasks like retrieve a user's cart, update a customer's profile, and so on. This layer then calls into the Commerce Engine Core using DTOs and domain transformers to perform the tasks that were initiated by the rest resource. By having a granular set of integration bundles and communicating with DTOs, this layer's resource integrations can be customized to integrate with other back-end systems. For more information on how DTOs and domain transformers communicate with the Commerce Engine Core, see Interfacing with the Elastic Path Core. For tutorials on customizing Cortex API's Integration layer, see Introduction to Cortex API Resources.
