Initially, the terminology and concepts for Items, Item Definitions, components, and Item Definition Options may be confusing for client app developers. Particularly for developers who are more familiar with Elastic Path's core platform's terminology and concepts. Keep in mind Cortex API is designed to live in front of different applications, not just Elastic Path's e-commerce platform, so the API's terminologies and concepts are designed to fit this multipurpose model, see Why Use These Terminologies? below for more explanation on this.
Below are some of the key terminologies and concepts used in Cortex API.
An Item is a purchasable good like a T-Shirt, movie, song, entitlement...basically anything that can be purchased through Cortex API is an item. The Items resource's responsibility is to handle the item's purchasability, which is why availabilities, prices, and the addtocart form are on the item.
An Item Definition is a description of an Item. The item's name, media assets (pictures of the item), options, and details (characteristics of the item) are all part of the item definition.The Item Definitions resource's responsibility is to handle the merchandising data that describes the item.
Item Definition Options
An Item Definition Option is a variant of the item. For example, the item may be geta movie, Finding Nemo, which has an Item Definition Option called Video Quality. Video Quality has two choices: Standard Definition or High Definition. The two different resolutions, Standard Definition and High Definition, are the item option's choices, while the Video Quality is the Item Definition Option. The Item Definition Options' resource is responsible for listing the options available for an item, while the itemselections resource is responsible for the Selectors used to select choices for the option.
Items can have components, which are other items. For example, the item may be a Sci Fi Classics Movie Package and movies in the package are item components. You can have nested item components inside other item components. For example, the Sci Fi Classics Movie Package item could have the movie Forbidden Planet as a component and it could have the Star Wars Trilogy package as a component. The Star War Trilogy package then has 3 other components, each of which are components. In most cases, components can be purchased separately by following the component's standaloneitem link. For more information, resource_api_reference.html#ReadItemDefinitionComponent Read Item Definition Component in the Resource Reference Guide.
How do I access Items, Item Definitions, and Item Definition Options?
Start with the item. Most of the API Entry Points, searches, navigations, and slots, point to items. From items, you access the Item Definitions and Item Definition Options. This may seem like a long path to take in order to get the Item Definitions and the Item Definition Options, but by using Zoom, see Zoom, you can get all this data with one request.
Why Separate Items, Item Definitions, and Item Options?
Three words: REST Level 3. Cortex API is a REST Level 3 API, which means the API's responsibilities are broken up into individual units called resources. Each resource is designed to be responsible for the smallest amount of tasks as possible, which is why we separated Items, Item Definitions, and Item Definition Options into different resources. Compartmentalizing responsibilities into different resources provides a lot of flexibility for switching resources out, adding new ones, and even removing existing ones.
Aren't Item Definition Options actually separate Items?
Yes you're right, technically they are. The Finding Nemo Standard Definition and High Definition movie are two separate discs, they even have different packaging, but Cortex API organizes them under one item with different item options. This is similar to how the core platform's multi-SKU products are organized in the storefront.
Why use these Terminologies?
Cortex API is designed to live not just on top of our e-commerce platform, but also on top of other e-commerce platforms and even other applications. So the terminology used to describe its concepts is chosen to be in line with a multipurpose software model. For example, SKU (Stock Keeping Unit) is a term usually reserved for describing physical products in a store, but Cortex API may be placed in front of an application where the store doesn't have physical goods, it has entitlements, so the term SKU doesn't quite fit here. Instead, the term Item is a better fit to describe SKUs and products because it's generic enough to encompass both physical and non physical goods. The same goes for SKU Options, which are known as Item Definition Options in Cortex API. The term Item Definitions doesn't have a good mapping to other known e-commerce terminology, but just think of Item Definitions as descriptions of the Item, which include its name, details, components, options, and images.