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:
- Routing requests to proper endpoint URLs
- Ensuring all calls to Kibo eCommerce use the correct API context
- Authenticating your app with Kibo eCommerce
- Creating and regenerating access and refresh tokens
- JSON conversion
- Event handling and decrypting/validating event message
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:
- The authentication ticket your application uses to complete API calls
- The resource URI you want to query
- The API context in the request header
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
- 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.
- 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
- 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:
- 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}
- 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
- Retrieve the domain name for the URI endpoint
- Use the tenant URL to perform API operations
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:
- In the Tenants resource, run a GET operation using the following URL: http://home.mozu.com/api/platform/tenants
- In the request header, specify the x-vol-app-claims header, using the application's access token as the value.
- 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:
- In the application, in the Tenants resource, run a GET operation using the following URI: http://home.mozu.com/api/platform/tenants/{tenantid}
- In the request URI, enter the tenant ID you retrieved in the previous procedure.
- In the request header, specify the
x-vol-app-claims
header, using the application's access token as the value. - 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:
- In the application, run the operation you want to perform, using the URL retrieved in the previous procedure: {domainname}/api/{resourcepath}
- In the request header, specify the API context and the auth ticket (as the
x-vol-app-claims
).