Ecommerce Web API

The Dynamicweb Ecommerce web API is split into several controllers. This documentation describes the latest/current version of the controllers, currently:

  • The Product Controller
  • The Payment Controller (pending)
  • The Feed Controller (pending)

We recommend using a dedicated tool when working with or testing web APIs, as a browser is simply not the best tool for the job. Look into using Postman, Advanced REST client (chrome plugin), or similar tools.

All web API controllers are placed in url based upon these two patterns:

HTML
dwapi/{ControllerName}/v{versionNumber}/{action}/{id:optional} or dwapi/{ControllerName}/{action}/{id:optional}

For the product controller, the URL could look like this for the four available methods:

Method

URL string example

Comments

GetProduct

dwapi/Products/GetProduct/PROD65

 

GetProductGroupList

dwapi/Products/GetProductGroupList/GROUP43

 

GetProductList

dwapi/Products/GetProductList

 

VerifyConnection

dwapi/Products/VerifyConnection

 

And if you wanted to reach fx. GetProductList version 1, you could write:

HTML
dwapi/Products/v1/GetProductList

The parameters required by the four methods are discussed in a later section, after the overall idea is presented.

When querying for data you must build a state to use for the request, because the webapi itself is stateless. In concrete terms, this means that you MUST supply certain parameters when requesting data from the web API or the request will fail. This is a contrast to Ecommerce, where we currently maintain a state for all requests, and retrieve relevant data based on that. But the weapi is never going to maintain a state.

The request-state requires Language and Currency to be supplied  – Dynamicweb has too much data which does not make sense without specifying these two values. Other request-state information is optional and results in different data being fetched ({figureref).

Figure 3.1 Querying for data

Of course, the situation may require other parameters; if you want to retrieve data related to VAT you must supply a country code to base the VAT calculation on – if not supplied, VAT cannot be calculated and will be returned as uncalculated(0).

The Product Controller exposes Get-methods for working with product data. They are all nullipotent (no side-effects) and our goal is a RESTful implementation.

The following is a short overview of which query parameters to pass the method – these can change over time, so the below may not be completely accurate, but still give some indication as what to do. Note that FilledProperties will be explained in detail, later.

  • VerifyConnection
    • This method requires no further parameters, but simply verified whether you can reach the web serve or not
  • GetProduct/GetProductGroupList
    • LanguageId (required) – specifies the ecommerce language to return
    • CurrencyId (required) – specifies the currency to return
    • CountryId – specifies which country to use for VAT calculations
    • ShopId – indicates which image pattern to use for product images
    • FilledProperties – indicated which data to return
  • GetProductList
    • ProductIds (required) – Specifies which products to fetch for the list
    • LanguageId (required) – specifies the ecommerce language to return
    • CurrencyId (required) – specifies the currency to return
    • CountryId – specifies which country to use for VAT calculations
    • ShopId – indicates which image pattern to use for product images
    • FilledProperties – indicated which data to return

These methods expose the underlying data in the application through viewmodels, that can be configured to be filled with data based upon the method query.

These combined parameters define the state of the data you receive.

To control which data you want returned from a model you use the FilledProperties parameter to request specific properties. You can include or leave our any of the properties on the ProductViewModel.

So, if you want only the ID, variantId and Name returned you simply specify only those properties on the FilledProperties parameter:

HTML
/dwapi/Products/GetProductList?ProductIds=PROD133,PROD134&LanguageId=LANG1&CurrencyCode=DKK&FilledProperties=Id,VariantId,Name

The data returned then contains only the product ID, the variant ID, and the Name (and the Created timestamp) (Figure 5.2).

Figure 5.2 The data returned

Note that all null values (reference types) are removed from the result, while all “non-nullable” values (value types) are returned as the default value (0 or DateTime.MinValue). No work is being done to fetch this data – it is only provided because the underlying json serializer cannot be configured to exclude this data in the same way that null values can be filtered.