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
  • The Feed Controller

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.

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 verifies whether you can reach the web server 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 – indicates which data to return
    • UserID - specifies a userid to use for price & discount calculations. Leave blank to return for anonymous users. 
  • 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
    • UserID - specifies a userid to use for price & discount calculations. Leave blank to return for anonymous users. 

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.

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 4.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).

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.

The payment controller exposes methods which makes it possible to capture, return, or cancel orders from external systems:

  • Capture is used for full and partial captures, if supported by the payment gateway
  • Return moves the order to RMA and refunds it, if supported by the payment gateway
  • Cancel cancels an an order

Here are the relevant parameters:

Method

Parameters

Description

Example

Capture

OrderID

Required. Specifies the id of the order being captured. Full capture.

/dwapi/payments/capture/{orderid}

 

Amount

Specifies an amount to capture. For partial captures – not supported by all gateways.

/dwapi/payments/capture/{orderid}/{amount}

Return

OrderID

Specifies the id of the order to return. Moves order to RMA – some gateways support immediate refunds, others require RMAs to be manually processed.

/dwapi/payments/return/{orderid}

 

Amount

Specifies an amount to refund – not all gateways support partial refunds.

/dwapi/payments/return/{orderid}/{amount}

Cancel

OrderID

Specifies the id of the order to cancel

/dwapi/payments/cancel/{orderid}

The feed controller exposes methods for retrieving an output based on a specific feed.

he 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

  • VerifyConnection

    • This method requires no further parameters, but simply verifies whether you can reach the web server or not.

  • GetFeedOutput

    • Id (required) – specifies the id of the feed to return

    • LanguageId (required) – specifies the ecommerce language to return

    • CurrencyId (required) – specifies the currency to return

    • ShopId – indicates which image pattern to use for product images