ECommerce API methods and their parameters - Introduction

• General attributes and elements
  • The refreshconfiguration-attribute
  • The includetiming-attribute
  • TotalCount-Element

In the articles of this chapter we will take a detailed look at all of the methods you can call in EC API.

All ECommerce API methods looks like the following:

<Execute method="<Method Name>" refreshconfiguration="true|false" includetiming="true|false">
  <Parameter id="<Parameter Name 1>" value="<Parameter value 1>" />
  … more parameters could be here …
  <Parameter id="<Parameter Name n>" value="<Parameter value n>" />
</Execute>

The method-attribute is mandatory. It tells the ECommerce API which method you would like to call.

General attributes and elements

The refreshconfiguration-attribute

The refreshconfiguration-attribute is optional and defaults to false. When set to true it instructs the ECommerce API to refresh its internal caches for the supplied channel (supplied in a parameter as shown later). In order to respond as fast as possible mappings, settings and features are cached internally by EC. This is good for performance, that these data is not constantly reread from database.

Generally when you use the API Query Tool you are often modifying the setup (Mappings, Features and maybe even Settings) and hereby often want to refresh configuration. In a test or live environment, you would have a static setup and these items need not to be refreshed. So it is generally recommended to turn it off in production environments.

How much time the refresh uses, of course, depending on how many channels, mappings etc. you have combined with what hardware you have and how busy it is. It would normally be in the range of a very few seconds often less than a second.

The includetiming-attribute

In addition, from version 4.6.21, the total time spent by the ECommerce API method is always returned as part of the result. It simply outputs the time spent as an attribute on the response node. Furthermore the attribute includetiming was introduced on the Execute-call. When that is set to true the ECommerce API, in addition to total-time, also outputs what the time was spent on as 3 individual durations:

• lockwait: How much time the method waited until execution started (ECommerce API is single threaded, so it will wait for previous called methods to complete).
• refresh: How much time was spent refreshing the configuration if needed.
• execution: How much time was spent executing the method.

The total-attribute, which will always be there, is the total duration of the 3 durations above.

Example: This method will fetch 100 products for Channel A. Note that ECommerce API is asked to refresh its configuration for the channel named Channel A and include timing info in the response:

<Execute method="GetProducts" refreshconfiguration="true" includetiming="true">
  <Parameter id="Channel" value="Channel A" />
  <Parameter id="Index" value="0" />
  <Parameter id="MaxCount" value="100" />
</Execute>

The result looks like this:

<Response total="00:00:36.227" lockwait="00:00:00.000"
          refresh="00:00:29.556" execution="00:00:06.671">
  <Result>
    <Channel name="Channel A">
      <TotalCount>100</TotalCount>
      <Products>
      ... The 100 Product-elements removed for brevity ...
      </Products>
    </Channel>
  </Result>
<Response>

Notice how there was no waiting to get the lock (no running methods) and that it took a little less than 30 secs to refresh the configuration (configuration is huge) and 7 secs to fetch the 100 products.

From version 4.7.9/4.8.2 includetiming will also contain a breakdown of time spent on each internal routine used. This breakdown can contain valuable info for figuring out what part of an ECommerce-query that is slow. This is shown here below. Notice that most ECommerce API-method calls does a Perfion Query followed by an Xsl-transformation. Some does a few more of these pairs (e.g. GetProducts in order to fetch, for example, Variants) and adding “refresh configuration” will add a substantial number.

The xml below shows the result of a “GetProducts” with includetiming set to true:

<Response total="00:00:36.7765714" lockwait="00:00:00.0029974"
          refresh="00:00:03.4631413" execution="00:00:33.3104327">
  <Timings>
    <Timing commercemethod="BuildEntities" operation="PerfionQuery" duration="00:00:00.4640457" />
    <Timing commercemethod="BuildEntities" operation="XslTransform" duration="00:00:00.0239664" />
    <Timing commercemethod="BuildChannels" operation="PerfionQuery" duration="00:00:00.0540287" />
    <Timing commercemethod="BuildChannels" operation="XslTransform" duration="00:00:00.0029976" />
    <Timing commercemethod="BuildEntities" operation="PerfionQuery" duration="00:00:00.0059967" />
    <Timing commercemethod="BuildEntities" operation="XslTransform" duration="00:00:00" />
    <Timing commercemethod="BuildChannels" operation="PerfionQuery" duration="00:00:00.0060132" />
    <Timing commercemethod="BuildChannels" operation="XslTransform" duration="00:00:00" />
    <Timing commercemethod="BuildSettings" operation="PerfionQuery" duration="00:00:00.1088928" />
    <Timing commercemethod="BuildSettings" operation="XslTransform" duration="00:00:00.0289839" />
    <Timing commercemethod="BuildUnresolvedMappings" operation="PerfionQuery" duration="00:00:00.0959541" />
    <Timing commercemethod="BuildUnresolvedMappings" operation="XslTransform" duration="00:00:00.0580206" />
    <Timing commercemethod="ResolveMappings" operation="XslTransform" duration="00:00:00.1539672" />
    <Timing commercemethod="BuildFeaturesForCategory" operation="PerfionQuery" duration="00:00:00.0249828" />
    <Timing commercemethod="BuildFeaturesForCategory" operation="XslTransform" duration="00:00:00.0459539" />
    <Timing commercemethod="BuildFeaturesForProduct" operation="PerfionQuery" duration="00:00:00.2880019" />
    <Timing commercemethod="BuildFeaturesForProduct" operation="XslTransform" duration="00:00:00.6631904" />
    <Timing commercemethod="BuildFeaturesForVariant" operation="PerfionQuery" duration="00:00:00.1960853" />
    <Timing commercemethod="BuildFeaturesForVariant" operation="XslTransform" duration="00:00:00.5109622" />
    <Timing commercemethod="MergeMappingsWithFeatures" operation="XslTransform" duration="00:00:00.3431402" />
    <Timing commercemethod="GetProducts" operation="PerfionQuery" duration="00:00:10.2074213" />
    <Timing commercemethod="GetProducts" operation="XslTransform" duration="00:00:23.0550332" />
  </Timings>
  <Result>
    <Channel name="B2CPrincess">
      <TotalCount ignoringpaging="39973">1000</TotalCount>
      <Products>
        <!-- A lot of products omitted for brevity -->
      </Products>
    </Channel>
  </Result>
</Response>

Notice that final two Elements for “GetProducts”. They are the most time-consuming parts. The Query getting the 1.000 products from Perfion takes approx.10 secs while the xsl-transformation accounts for 24 secs.

The samples the comes in this chapter always omit the includetiming-attribute and the duration(s) included in the results.

TotalCount-Element

Whenever fetching data (Entities) from the ECommerce it will always return the number of entities returned. It looks like this:

<TotalCount>128</TotalCount>

And shows that 128 entities are in the result. GetProducts will from version 4.7.9/4.8.2 return an additional count. You can read more on that in Section GetProducts.