Application Development Requirements

Kibo eCommerce is designed for extensibility. Through our REST API, you have complete access to the operations and entities you need to develop Kibo eCommerce applications. We also provide robust SDKs that you can use to write Kibo eCommerce apps in the language of your choice.

Advantages of the Kibo eCommerce SDKs

Kibo eCommerce strongly recommends using one of our SDKs for app development. If you use an SDK, all of the following tasks are handled behind the scenes by the SDK:

The remainder of this topic explains these concepts as they pertain to all Kibo eCommerce applications. Refer to the readmes and code comments for each SDK for more specific information.

Requests to the Kibo eCommerce API

To facilitate application development, the API for all platform/application-level services is hosted behind a generic domain:

home.mozu.com

Your application can send requests to this domain by including it in the request path. For example, you can use the path:

http://home.mozu.com/api/platform/applications/authtickets

to send an authentication request to Kibo eCommerce.

Requests to the Kibo eCommerce API require the following information:

Supported Response Formats

The Kibo eCommerce API supports the JSON response. When sending an API request, you can select the format to return by defining the value in the HTTP accept header, using the following syntax:

	accept:application/json
	accept:text/json

The response includes an HTTP Content-Type header with the same value specified in the accept header.

API Context

For any request your application sends to Kibo eCommerce, the request header must include an API context. The tenant is almost always required. Many operations also require context for the master catalog, catalog, and site. The following is an example of a common API context: 

	x-vol-tenant: 0000
	x-vol-master-catalog: 1
	x-vol-catalog: 1
	x-vol-site: 11111

The values in red are sample values that you must replace with your own data.

Tip: If you are using one of the Kibo eCommerce SDKs to develop your application, you can look at the ApiContext and Headers files at the top level of the source directory to see how the API context is implemented and what headers you can include in your Kibo eCommerce requests.

Supported Headers

Header Type Value
x-vol-catalog request and response The identifier of the catalog. Your first catalog is 1, the second catalog is 2, and so on.
x-vol-master-catalog request and response The identifier of the master catalog. Your first master catalog is 1, the second catalog is 2, and so on.
x-vol-site request and response The unique identifier of the site. When you log in to Admin, this number appears in the URL for the Site Builder module, preceded by an "s-". For example: https://t0000.sandbox.mozu.com/Admin/s-11111/website in a sandbox environment.
x-vol-tenant request and response The unique identifier of the tenant. This number appears in your site’s URL in Admin, preceded by a "t". For example: https://t0000.sandbox.mozu.com/Admin/m-1/ in a sandbox environment.
x-vol-site-domain request and response The fully qualified URL of the site for which to complete the request. Supplying this header automatically supplies tenant, site, and catalog values.
x-vol-tenant-domain request and response The fully qualified URL of the tenant for which to complete the request.
x-vol-has-error response If true (1), the response contains an error.
x-vol-user-claims request The access token value of the user's authentication ticket.
x-vol-app-claims request The access token value of the application's authentication ticket.
x-vol-locale request and response The code of the content locale. For example: en-US
x-vol-version request and response The version of the API to use in the request. If the version is not specified, the request uses the latest available version.
x-vol-currency request and response The three-letter ISO 4217 standard global currency code. For example: USD
x-vol-correlation request An optional GUID used to associate multiple log entries in a cascading chain of API requests.
x-vol-dataview-mode request The mode in which to view runtime data, which is Live or Pending.
x-vol-accept request The response format to accept in this request.
x-vol-Content-Type request and response The MIME type of the request body, used with POST and PUT requests.

Authentication

Any application that calls into the Kibo eCommerce API must authenticate with the API. The authentication process generates an authentication ticket that contains an access token and a refresh token, as well as expiration information for each token:


	{
		"accessToken": "string",
		"accessTokenExpiration": "DateTime",
		"refreshToken": "string",
		"refreshTokenExpiration": "DateTime"
	}
When you create an application in Kibo eCommerce Dev Center, Kibo eCommerce automatically generates an Application Key and a Shared Secret for the application. You use these values to authenticate. Tip: The Kibo eCommerce SDKs include logic that handles authentication for you using your API context and the Application Key and Shared Secret. For example, if you are using the Kibo eCommerce .NET SDK, you can add this information to the app.config file: 

	<configuration>
		<appSettings>
			<add key="ApplicationId" value="AppKeyFromDevCenter" />
			<add key="SharedSecret" value="SharedSecretFromDevCenter" />
		</appSettings>
		…
	</configuration>

Access and Refresh Tokens

An access token establishes an application’s identity. When an app calls a specific Kibo eCommerce API operation, the access token is passed as part of the application claims information in the request header.

Refresh tokens allow an application to refresh an expired access token without re-authenticating the entire application. After the access token expires, the refresh token can use the Application Key and Shared Secret to generate a new authentication ticket that contains the same refresh token and refresh token expiration, but contains a new access token and access token expiration.

Both access tokens and refresh tokens are subject to expiration. After the refresh token expires, you must generate a new authentication ticket.

Note: Access tokens are viewable and readable for external programs.

Refresh tokens should never be shared. Always protect information about your refresh token and shared secret.

Generate an Authentication Ticket

  1. Copy your Application Key and Shared Secret from Dev Center. Go to Develop > Applications and double-click the app you are developing to view this information.
  2. In your external application, run a POST operation in the platform/applications/authtickets resource using the following URL: http://sandbox.mozu.com/api/platform/applications/authticketsNote: The above is a test URL and refers to the sandbox environment. Your complete and certified app will make requests using the production URL: http://home.mozu.com/api/platform/applications/authtickets
  3. In the request body, enter the Application Key and Shared Secret. Note: The Application Key property appears as “applicationId” in the REST API. All current applications use the full Application Key value for this field.

    Legacy applications use the Application ID instead of the Application Key. The Application ID is part of the Application Key, which is in the format: <dev account namespace>.<application ID>.<application version>.<package name>.

The system returns the refresh token, access token, and expiration information.

Refresh an Authentication Ticket

If the access token has expired but the refresh token is still valid, complete the following steps to refresh the authentication ticket:

  1. In the platform/applications/authtickets resource, run a PUT operation using the following URL: http://sandbox.mozu.com/api/platform/applications/authtickets/refresh-ticket/{refreshToken}
  2. In the request URL, enter the refreshToken value string.

The system returns the refresh token, access token, and new expiration information.

Run Kibo eCommerce Operations from an Application

After you provision a sandbox, install an application in that sandbox, and generate an authentication ticket for the application, you can begin to run Kibo eCommerce API operations using the application.

Running an operation in the Kibo eCommerce API consists of the following procedures:

Retrieve the Tenant ID

You can view the tenant ID for a sandbox in the sandbox URL in Admin, or you can get it programmatically using the API:

  1. In the Tenants resource, run a GET operation using the following URL: http://home.mozu.com/api/platform/tenants
  2. In the request header, specify the x-vol-app-claims header, using the application's access token as the value.
  3. In the request body, note the tenantID value.

Retrieve the Domain Name for the URI Endpoint

To retrieve the domain name the application uses to run Kibo eCommerce API operations in a development store, complete the following procedure:

  1. In the application, in the Tenants resource, run a GET operation using the following URI: http://home.mozu.com/api/platform/tenants/{tenantid}
  2. In the request URI, enter the tenant ID you retrieved in the previous procedure.
  3. In the request header, specify the x-vol-app-claims header, using the application's access token as the value.
  4. In the request body, note the following information:
    • The DomainName value for the tenant, which appears as: {tenantID}.{host name}.mozu.com
    • The master catalog ID values for the tenant.
    • The catalog ID values for the tenant.
    • The site ID values for the tenant.

Use the Tenant URL to Perform API Operations

To use the sandbox domain name for the development store to begin performing Kibo eCommerce API operations using the application, complete the following procedure:

  1. In the application, run the operation you want to perform, using the URL retrieved in the previous procedure: {domainname}/api/{resourcepath}
  2. In the request header, specify the API context and the auth ticket (as the x-vol-app-claims).