API Overview

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=

The value after the word "Basic" is a Base64 encoded string that consists of a username and password separated by a pipe character (username|password), as described below:

• 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) are 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.

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" />

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.

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

Indentation

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

Setting the indent parameter to true will produce a response with the JSON string properly indented, similar to this sample attributes response:

"Attributes": [
    {
        "AttributeId": 2,
        "AttributeTypeId": 1,
        "DisplayOrder": 1,
        "ExternalId": null,
        "IsActive": true,
        "Name": "Red",
        "OldAttributeId": null
    }
]