TABLE OF CONTENTS

• Authentication
• Enabling/Disabling Authentication
• During Development
• HTTPS and SSL
• Caching
  • Cache.config
• Cache Refresh
• Configuration
• HTTP Methods
• HTTP Status Codes
• Errors
• Expands
• Filters
• Sorting
• Paging
• Indentation
• Examples

The Znode API is organized around REST and is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. The API uses built-in HTTP features — such as headers, methods, and status codes — which can be understood by any off-the-shelf HTTP client. The Znode API only supports requests and responses in JSON format.

Authentication

The Znode API uses basic authentication with the Authorization header to validate requests. An example of the format for the Authorization header is shown below:

Authorization: Basic d3d3Lm15LXN0b3JlLmNvbXw1RDJCNEM1RS1EOEIzLTQ0ODgtOTA0RC02NDA5NDc2MkUxMzY=

• Username: This is the domain name for the store whose data will be retrieved during the request (i.e. www.my-store.com).

• Password: This is the API key for the domain, as found in the ZnodeDomain table in the Multifront database (i.e. 5D2B4C5E-D8B3-4488-904D-64094762E136).

Any client of the Znode API must concatenate the domain name (username ) with the domain key (password), separated by a pipe, and then Base64 encode that string to pass along in the Authorization header.

When a request is made to an endpoint, the Znode API will look for the Authorization header and try to decode it. It will then split the decoded string into the domain name (username) and domain key (password), verify that they are a match, then process the request.

If the Authorization header isn't in the request or if either the domain name (username) or domain key (password) is empty, the API request will fail with the following information:

• HTTP status code: 401 Unauthorized

• HTTP status description: Domain name and key are either incorrect or missing from the request Authorization header.

Enabling/Disabling Authentication

Authentication can be disabled by setting ValidateAuthHeader to false in the <appSettings> section of the API's web.config file. However, in most cases, this value should be set to true in production environments.

<add key="ValidateAuthHeader" value="true" /> (This is the Parent key, when set to true, it will start the authentication process for API.)

<add key="IsGlobalAPIAuthorization" value="true" /> (When set to true, this key will enable Global APIs Authorization. For the same, it is required to set a single API domain name and its respective API domain keys. When set to false, the individual domain name and its domain keys need to be set. )

<add key="EnableTokenBasedAuthorization" value="false" /> (When set to true, it adds the additional token-based authentication along with validating the auth header.)

Note: 'IsGlobalAPIAuthorization' Key and 'EnableTokenBasedAuthorization' will work only if  'ValidateAuthHeader' key value is set to true

During Development

When developing a client that uses the Znode API, it will be useful at times to open endpoints in a browser in order to see data. To ensure this is possible, you need to add an entry in the ZnodeDomain table for the domain of the API itself. In this case, simply disabling authentication will have no effect.

For example, if you have the API deployed locally at "api.localhost.com", you should add an entry in the ZnodeDomain table where the DomainName field is "api.localhost.com" with the relevant portal ID. This will be the context for retrieving data when viewing endpoints in a browser.

IMPORTANT: This should be for development purposes only.

HTTPS and SSL

The requirement to run under HTTPS is specific to your requirements and infrastructure; therefore, the Znode API doesn't force you to use HTTPS to run it. However, we strongly recommend it, especially for production environments. During development, it would be beneficial to create and install a local SSL certificate in order to properly mimic all calls to the Znode API.

Caching

The Znode API has its own caching layer in order to provide the best possible performance when retrieving data. Caching occurs only for GET requests; it is not supported for POST, PUT, or DELETE requests.

Cache.config

All cache settings are defined in the cache.config file, a portion of which is shown below:

<ZnodeApiCache>

    <cache enabled="true">

        <routes>

            <route template="products/{productId}" enabled="true" sliding="true" duration="60" />

            <route template="products" enabled="true" sliding="true" duration="60" />

        </routes>

    </cache>

</ZnodeApiCache>

The <routes> node contains a list of <route> nodes, each with the following properties:

• template - The route template as defined in the \App_Start\WebApiConfig.cs file.

• enabled - True/false value that determines if caching is enabled for the route (default = true).

• sliding - True/false value that determines if a sliding cache is used for the route; if false, absolute caching is used (default = true).

• duration - The number of seconds that the response data for the route should be kept in cache (default = 60 seconds).

Cache Refresh

In addition to the caching settings defined in the cache.config file, you can refresh the cache for a route by using the cache parameter and setting its value to "refresh", such as in this example:

GET http://api.mysite.com/products/302?cache=refresh

Configuration

The default configuration for the Znode API should work for most implementations. However, there are a couple configuration items worth noting:

<add key="UriItemSeparator" value="," />

<add key="UriKeyValueSeparator" value="~" />

GET http://api.mysite.com/products?filter=name~cn~pea,saleprice~gt~4.99

But what if the product catalog is for Great Britain, where the comma is used for decimal places instead of the period? This would make the above request look like this:

GET http://api.mysite.com/products?filter=name~cn~pea,saleprice~gt~4,99

HTTP Methods

The Znode API uses standard HTTP methods as actions for all API requests, and most URIs accept multiple HTTP methods (one per request). The table below is a general rule of thumb for which HTTP methods are used and when.

HTTP Status Codes

The Znode API uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate a server error.

Errors

The Znode API has robust error-handling capabilities and will include additional information about the error if an HTTP 500 status code is returned. Every response from the Znode API includes the following properties:

Below is an example of what these properties look like as part of a response:

{

    "ErrorCode": null,

    "ErrorMessage": "SKU ID 304 does not exist.",

    "HasError": true

}

The Znode API supports the concept of expands, which allows a client to retrieve related entities for a given item during the same request, and made possible with the expand parameter. For example, a client can retrieve a product (id = 329) and its images by using the following endpoint:

GET http://api.mysite.com/products/329?expand=images

GET http://api.mysite.com/products/329?expand=images,addons,promotions

Filters

The Znode API also supports filters, which are essentially SQL where clauses that limit the results for a request. The filter parameter consists of tuples, with each item in the tuple separated by the ~ character. The filter tuple takes the following format:

key~operator~value

For example, to retrieve all products whose name contains "pea", a client will use the following endpoint:

GET http://api.mysite.com/products?filter=name~cn~pea

GET http://api.mysite.com/products?filter=name~cn~pea,saleprice~gt~4.99

GET http://api.mysite.com/products?filter=externalid~eq~null

GET http://api.mysite.com/products?filter=externalid~ne~null

Sorting

When retrieving lists of items, the Znode API supports using the sort parameter to sort the results. For example, to retrieve all products sorted by name in ascending order, a client will use the following endpoint:

GET http://api.mysite.com/products?sort=name~asc

GET http://api.mysite.com/products?sort=name~asc,retailprice~desc

Paging

In many cases, retrieving lists of items needs to be done a page at a time, which the Znode API handles by providing the page parameter. For example, to retrieve page 4 of a list of products with a page size of 25, a client will use the following endpoint:

GET http://api.mysite.com/products?page=index~3,size~25

For endpoints that support paging, the following properties will be returned in the response:

If an endpoint supports paging, there will be a Paging section as part of its help page; otherwise, no Paging section will be shown. Below is an example of what these properties look like as part of a response:

{

    "PageIndex": 3,

    "PageSize": 25,

    "TotalPages": 5,

    "TotalResults": 108,

}

Because all responses in the Znode API are JSON strings, it can sometimes be hard to read responses with the human eye, especially for large responses. While this doesn't matter to machines, it can be useful at times to open an endpoint in a browser to see the results. For this, a client can use the indent parameter for better readability, as such:

GET http://api.mysite.com/attributes?indent=true

"Attributes": [

    {

        "AttributeId": 2,

        "AttributeTypeId": 1,

        "DisplayOrder": 1,

        "ExternalId": null,

        "IsActive": true,

        "Name": "Red",

        "OldAttributeId": null

    }

]

Below are some examples that show how you can use different combinations of the expand, filter, sort, and page parameters to retrieve various sets of data.

Get a list of products and their SKUs, where the product name contains "pea", sorted by wholesale price in descending order

GET http://api.mysite.com/products?expand=skus&filter=name~cn~pea&sort=wholesaleprice~desc

GET http://api.mysite.com/products?expand=categories&filter=name~sw~honey,number~cn~234

GET http://api.mysite.com/products?page=index~4,size~10&sort=name~asc

GET http://api.mysite.com/products?page=index~0,size~20&sort=saleprice~asc&expand=addons,categories,reviews