Datawiz BI is an Internet based service for analysis of retail-data provided by company's clients. To start using the service simply upload source data (receipts and some information) covering a significant time span (a year or more) and update it every day. Application Program Interface will help you with that - API - "Datawiz BI API v.1."

The interaction between Datawiz BI and a client is a typical client-server pattern, where Datawiz BI is the server and clients' software is the client. Based on this, we can easily figure out the key elements of their interaction:

1. Client addresses a server and establishes a connection
2. Client sends a request to a server
3. Server returns information or an error code
4. Connection stops

About the realization. Datawiz BI API v.1 uses [REST] technology (http://uk.wikipedia.org/wiki/REST), that simplifies the interaction between client and server. Hereinafter Datawiz BI API is shortened to REST API and lets get acquainted with its main elements:

To provide a server - client interaction REST API uses a standard HTTP protocol. According to this protocol, all information in the network is referred to as resources. Each resource has its unique Unified Resource Locator - [URL] (http://uk.wikipedia.org/wiki/URL)) - address that helps to identify a resource.

An example of a resource: http://api.datawiz.io/api/v1/ - shows a root entry of REST API v.1 service [datawiz BI] (http://api.datawiz.io)

As you see, the resource looks like a file system path, indicating an object inside. If you take a closer look you may notice: root directory - //; first level - domen name (api.datawiz.io); then there is a root directory name (api) on the server, next level - its specification (v1) and so on...

Client - server interaction within HTTP protocol starts with a client's request to the server. The client sends a request header and body to the server, stating command and all other necessary parameters in the header and the body contains a level (in JSON format) that has to be added or replaced on the server. A result of the client - server interaction is a server's response (header and body) with HTTP-code of the response and data (in JSON format). The cycle of client - server interaction repeats.

A standard set of HTTP protocol commands is used for the resource management:

Objects in the request body are provided in a certain format. The most popular formats for structural information presentation in REST API are [JSON] (http://uk.wikipedia.org/wiki/JSON), [XML] (http://uk.wikipedia.org/wiki/XML), [HTML] (http://uk.wikipedia.org/wiki/HTML). Datawiz BI API v.1 uses JSON format for interaction between application and HTML for presentation of API at the address: http://api.datawiz.io/api/.

Example of a server's response in JSON format to a client request GET http://api.datawiz.io/api/.json:

{
     "v1": "http://api.datawiz.io/api/v1/", 
     "v2": "not available yet" 
}

Client can choose a data format. It can be done in several ways (presented in the descending order of their priority):

1. Data format can be stated as URL suffix: .json (JSON) or .api (HTML). See previous example.
2. Data format can be stated as additional parameter format:?Format=json or ?Format=api. When suffix and parameter are stated at the same time, the suffix has a priority. Example: http://api.datawiz.io/api/?Format=api.
3. 3. Data format can be stated in the HTTP heading Content-Type indicating application/json or application/html. This method of selecting format works only in case when all other ways of stating a format are absent.
4. 4. If none of the presented methods is used, JSON format is chosen by default.

There are 2 types of REST API resources:

• collections
• objects

Collections- are object lists. Collections are represented as JSON arrays and used to send requests to server or to receive from server several objects at one request. Endpoint of the collection is always a recourse name.

Examples of "collection "type endpoints:

• /Products/ - to receive the first 10 elements from a Catalog or to send to the server a certain amount of items indicated by a client.
• /Receipts/ - to receive from the server the first 10 receipts or to send to the server a certain amount of receipts indicated by a client.
• /Receipts/1-1_20141120195527_297/cartitems/ - to receive a list (collection) of all purchases on the receipt with id=1-1_20141120195527_297

Collections can contain from zero to several dozens or hundreds thousands of elements. Receiving all these elements at once may overload a server, network and client's software, thus there is a need to limit the information coming from server.

It can be done with the help "pagination" of collection (pagenating). "Pagination " means dividing collections into pages and loading only one page per one request.

To manage collection "pagination" additional URL parameters are used:

For easy management of collection (including "pagination "management) each collection returns a client JSON-dictionary with 4 parameters:

• Count - overall number of objects in the collection
• Next - indicator (url) to the next "page" of the collection
• Previous - - indicator (url) to the previous "page" of the collection
• Results - array of all obects on the page. Number of the elements in the array is always smaller or equal to page_size.

Example of server's response to a request: "to return a collection of 2 items from Catalog in json":format

GET http://api.datawiz.io/api/v1/products/?Format=json&page_size=2:

{
     "count": 24880, 
     "next": "http://api.datawiz.io/api/v1/products/?page=2&page_size=2&format=json", 
     "previous": null, 
     "results": [
         {
             "url": "http://api.datawiz.io/api/v1/products/17786/", 
             "product_id": "17786", 
             "name": "\" La Festa \ "Cappuccino GV 12,5 * 10 * 8psc (natural/instant) (cream" 
         } 
         {
             "url": "http://api.datawiz.io/api/v1/products/17785/", 
             "product_id": "17785", 
             "name": "\" La Festa \ "Cappuccino GV 12,5х10х8psc (natura/instant) nut" 
         } 
     ] 
}

Object collections sent to server are managed by client. He can also choose a way of transferring data to the server - as singe objects or as a list. The following has to be emphasized: transferring single objects is a slow process and it is used when one or two objects have to be added of changed, while transferring a list significantly speeds up the process but makes management of separate objects more complicated. Moreover, the server has a limitation of transfered data size (approximately 200 Kb ~ 2000 objects), thus sometimes data has to be transfered to the server in segments.

Objects - are data structures in the form of JSON dictionaries where key words (keys) are fields, and data - values of fields. Fields may indicate included structures (dictionaries and arrays), buinding a complex structure of the object. To receive information about the structure of the object, you can send an OPTIONS request to the server. The endpoint of the object is a resource identifier

Examples of "object "type resources:

• /Products/*12345* - - to interact with a particular element from the Catalog with id = 12345
• /Receipts/*12345* - to get access to the receipt with id=12345
• /Receipts/*12345*/cartitems/*1* - - to read the first line in the receipt with id = 12345

Example of server's response to the request: "to return an article from the Catalog with id=77087-24316 in json"format: GET http://api.datawiz.io/api/v1/products/77087-24316/.json:

{
    "url": "http://api.datawiz.io/api/v1/products/77087-24316/", 
    "product_id": "77087-24316", 
    "name": ". 	smoked sausage. (kg)", 
    "category_id": "79", 
    "category_url": "http://api.datawiz.io/api/v1/categories/79/", 
    "unit_id": "3-1-0", 
    "unit_url": "http://api.datawiz.io/api/v1/units/3-1-0/"
}

If to state GET instead of OPTIONS to the same request, you will receive a description of the request structure:

OPTIONS http://api.datawiz.io/api/v1/products/77087-24316/.json

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
    "name": "Product Instance", 
    "description": "Object 'Products' stores information about products", 
    "renders": [
        "application/json", 
        "text/html"
    ], 
    "parses": [
        "application/json", 
        "application/x-www-form-urlencoded", 
        "multipart/form-data"
    ], 
    "actions": {
        "PUT": {
            "url": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "product_id": {
                "type": "string", 
                "required": true, 
                "read_only": false, 
                "max_length": 100
            }, 
            "name": {
                "type": "string", 
                "required": true, 
                "read_only": false, 
                "label": "name", 
                "max_length": 200
            }, 
            "category_id": {
                "type": "string", 
                "required": true, 
                "read_only": false, 
                "max_length": 100
            }, 
            "category_url": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }, 
            "unit_id": {
                "type": "string", 
                "required": true, 
                "read_only": false, 
                "max_length": 50
            }, 
            "unit_url": {
                "type": "field", 
                "required": false, 
                "read_only": true
            }
        }
    }
}

Description of the structure, received at OPTIONS request,helps to understand what data can be taken from the server and what data has to be prepared for alteration at the server. For example, when analyzing parameters required and read_only it is clear, what fields can be modified and which of then it is necessary to fill.

From presented above result of OPTIONS command we can see that in order to register a new item in Catalog you need to fill only 4 required fields: product_id, name, category_id and unit_id. It is easy to guess, that category_id and unit_id fields are identifiers from Catalog of "Categories of items" and "Measurement units".

Resource identifiers are used for reliable resource identification and their linkage. Object identifier is URL written in url string. Sometimes to load data from a related object it is enough to read the url string and to use it in a GET request. url strings are "read only" strings, thus is it not necessary to fill them when transferring objects to the server.

To get a better insight into REST API structure and commands it provides, you can use our test platform at http://api.datawiz.io/api/. To receive an access just use the same client name and password you use for login into the resource web-interface http://api.datawiz.io

At the moment, REST API uses 2 models of authentication:

1. OAuth v2 - with the help of name and password
2. Signature authentication (HTTP Signature Authentication)

Now, let's get acquainted with REST API resources. In general, REST API provides access to 8 resources:

1. Shops - - list of client's shops (read only)
2. Terminals - list of point-of-sale terminals for each shop
3. Categories - hierarchic list of items categories
4. Units - measurement units
5. Products - list of items (goods)
6. Loyalty - customer loyalty program
7. Cashiers - list of cashiers
8. Receipts/Cartitems - receipts

Resources 1 - 7 are Catalogs and they are necessary for receiving correct information about point 8 Receipts.

All resources are related to each other. Here is a short description of relations:

1. A service user (Client) may change several shops (Client->Shops). But not less that one. "One to many" relation
2. A shop (Shop)may have several point-of-sale terminals (Shop->Terminals). But not less that one. "One to many" relation
3. List of categories (Categories) - - is a hierarchic structure. Hierarchy is created with the help of parent_id, string, where an identifier of a parent category is written . There is one primary element of the hierarchy, where parent_id is not defined (empty) and contains a user's name in "Category name" string (the first level of hierarchy); categories of the second level are top hierarchy categories of items.
4. Measurement units (Units) can be whole (can be counted) (pieces) and decimal (can be divided into parts) (kilos). Packages can also be measurement units (box 12 pieces)
5. List of items (Products) contains product names. Each item is related (1:1 relation) to a measurement unit (Product->Unit) and to a category (Product->Category) (1:1 relation).In both cases, the relations have to be defined.
6. Loyalty program (Loyalty) - is data about the client - participant of a loyalty program (identification card, name, birthday...)
7. List of cashiers (Cashiers) - - is a global list (not related to one particular shop) of all cashiers (identifier, name)
8. Receipts . (Receipts) -- list of receipts. The central element of the structure. Each receipt is identified by a total of strings: "receipt date" (date) + "point-of-sale terminal" (terminal) + "receipt id" (check_id) and has the following relations:

• Receipt->Shop (1:1 relation) - receipt linked to a shop. The relation has to be defined
• Receipt->Terminal (1:1 relation) - receipt is linked to a particular terminal. The relation has to be defined
• Receipt->Cashier (1:1 relation) - - receipt CAN BE linked to a cashier. The relation CAN beNOT DEFINED
• Receipt->Loyalty (1:1 relation) - receipt CAN BE linked to a loyalty program (indicating a client making purchase) The relation CAN beNOT DEFINED
• Receipt->Cartitems (1:N relation) - - receipt contains 0 or more "units of goods" (Cartitems). Each unit (Cartitem) indicates an item from the "list of items" (Product) (1:1 relation) (the relation has to be defined),contains a price per one item, quantity and overall price of the unit. Remark: Cartitems is viewed not like separate resource, but like a part of Receipt.

The list of main REST API resources can be found at http://api.datawiz.io/api/v1/. A request to this resource returns the following JSON object of dictionary type: Request: GET http://api.datawiz.io/api/v1

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"terminals": "http://api.datawiz.io/api/v1/terminals/",
"products": "http://api.datawiz.io/api/v1/products/",
"cashiers": "http://api.datawiz.io/api/v1/cashiers/",
"units": "http://api.datawiz.io/api/v1/units/",
"shops": "http://api.datawiz.io/api/v1/shops",
"loyalty": "http://api.datawiz.io/api/v1/loyalty/",
"categories": "http://api.datawiz.io/api/v1/categories/",
"receipts": "http://api.datawiz.io/api/v1/receipts/"
}