Capillary APIs are structured following the REST model. Our APIs use HTTPS protocol and support requests and responses in JSON format.

HTTP methods

The HTTP methods used in Capillary APIs are as follows:

Know about API URL structure, host URL and headers

API URL structure

The below image displays Capillary API structure with an example:

The resource ID is a combination of the Entity and the action you tell the API to perform. In this case, adding a customer is the entity and add is the action. For more information on entities, see Entities management.

Host URLs

A host is a server to which the API calls are made, usually the API cluster URL.

The host URLs are the same for both v1.1, v2, and v3 APIs. However, the v1 APIs mentioned in the documentation have different URLs for each entity. You can see those URLs under the respective section.

Request Headers

API version

Capillary's APIs are divided into four versions:

• v1
• v1.1
• v2
• v3

These versions are not merely upgrades; they are a combination of:

• new sets of APIs that receive new version numbers, and
• upgraded versions of existing APIs.

The v1 APIs support both JSON and XML. The V2 and V3 APIs are developed in JSON.

Additional features of v2 and v3 APIs

The list below highlights the additional features that v2 and v3 APIs support compared to v1 and v1.1 APIs:

• Provide extended support for multiple sources, i.e., you can now manage accounts of different sources such as InStore, MartJack, WeChat, e-commerce and Facebook.

• Support multiple accounts of a single source. For example, an org could have multiple accounts on WeChat and Facebook. Each account will have a different account ID. You would need to pass the respective account ID when making API calls.

• Merge accounts automatically when the same identifier is registered in different sources. For example, assume that a customer has registered on InStore using his mobile number and e-commerce site using his email ID. Now, if the customer registers the same mobile number on the e-commerce site, the accounts will be merged automatically to a single customer ID. You can retrieve the customer details from various sources of an organization using the unique customer ID.

NOTE: By default, all the API versions are enabled for the organisations across clusters.

Tracking Request

A unique ID is generated for every request made using Capillary APIs and is sent to the requester in the Response Headers as X-Cap-Requestid. You can use this request id to track the request end-to-end. <aside class=“notice” It is recommended to note the X-Cap-Requestid of a request for future requirements.

When an API call is made with 4 batch transactions, A response header is generated with the X-Cap-Requestid as shown below. This ID can be used to track the details of the entire API call (both request and response).

{
  "Date": "Wed, 16 Dec 2015 06:05:13 GMT",
  "Content-Type": "application/json; charset=utf-8",
  "Cache-Control": "must-revalidate,no-cache,no-store",
  "X-Cap-Requestid": "5670FF17B7D58",
  "Server": "CapWS",
  "Content-Encoding": "gzip",
  "X-Cache": "MISS from localhost",
  "Transfer-Encoding": "chunked",
  "Connection": "keep-alive"
}

Organization setup

An organization associated with Capillary is registered in Intouch. Based on the organization’s architecture, store TILL or Store Center accounts are created besides zones, concepts, and stores. Only Capillary users have access to register an organization in inTouch. For more information, contact your Account Manager or Delivery Manager of Capillary.

To set up an organization as a Capillary admin, see Setting up Organization.