i.LEVEL API Introduction

Version 1.0 (June 2018) Welcome to the i.Level API! You can use our API to access i.Level API endpoints, which can get information on various resources in our database. The introduction looks at some key concepts that apply to the various API calls.

The following sections detail the key resources exposed with the API. Examples are provided in JSON format. Please review the Change Log for important updates.

Authentication

In order to use the API it is necessary to obtain a username and key. Support will create and issue this key from the instance of i.Level you wish to connect to. Please specify which resources and methods you will be using as these will be set up based on our agreement with our customer.

When making a call such as https://yumi.ilevelconnect.co.uk/api/warehouse developers must use Basic Auth to generate the "Authorization" header. The developer should follow Basic Auth principles (https://en.wikipedia.org/wiki/Basic_access_authentication) and pass the username and password for authentication. You can use Postman setting up Basic Auth to test your calls before putting into production.

Please Note

All API calls must be sent using HTTPS

Response Details

Example of header details

{
    "response": {
        "Page": 1,
        "PageCount": 2301,
        "RecordsSent": 1,
        "RecordsFound": 2301,
        "Stock": [
            {
                "SKUSize": "A0000001010A"
            }
        ]
    }
}

Each response from a GET call returns the same base structure. Header details provide information about pagination and record details.

Property	Example	Description
Page	1	The current page returned for the GET request
PageCount	13	The total number of pages that would need to be parsed based on the request and PageSize specified
RecordsSent	100	The number of records returned by the request
RecordsFound	1296	The number of records found based on the request parameters

Request Pagination

Due to the number of records that can be returned from any given request it is necessary to control the size of the response. This is done through pagination control. The table below shows the pagination request parameters which can be used.

Property	Example	Description
Page	URL/api/stock?page=2	The page that you wish to retrieve. By default the first page will be returned.
PageSize	URL/api/stock?page=2&pagesize=250	The maximum number of records you wish to return. The default is 100 and the maximum is set at 1000

Count

Example count response

{ "count": 581 } Sometimes you may simply want to check how many records might be returned by a GET request. This can be done with the count parameter.

Property	Example	Description

Property Example Description Count | URL/api/stock/count?sku=a@ | Returns a count of the number of records where SKU starts with 'A'.

Filtering

https://URL/api/stock?barcode=5060395910013

{
    "response": {
        "Page": 1,
        "PageCount": 1,
        "RecordsSent": 1,
        "RecordsFound": 1,
        "Stock": [
            {
                "SKU": "A0000001010",
                "SKUSize": "A0000001010A",
                "Colour": "OFF WHITE",
                "Size": "S",
                "Size_Sort": 1,
                "Barcode": "5060395910013",
                "Style": "A0000001",
                "Article": "FLORAL 1",
                "Size_Range": "S - 3XL",
                "In_Stock": 58,
                "Demand": 0,
                "Supply": 2,
                "Available": 60,
                "Web_Description": "",
                "Product_Group": "Long Sleeve Shirts",
                "Brand_Name": "iLEVELman",
                "Season": "AW16",
                "Brand_Style": "",
                "Cost_Centre": "",
                "Foreign_Stock_Code": "",
                "Origin": "China",
                "Fabric_Content": "100% Cotton",
                "Stock_Change_TS": "20170320153348",
                "Discontinued": false,
                "Retail_Price_Own_Currency": 32,
                "Retail_Price_Currency1": 0,
                "Retail_Price_Currency2": 0,
                "Sell_Price1": 12,
                "Sell_Price2": 0,
                "Sell_Price3": 0,
                "Sell_Price4": 11.5,
                "Sell_Price5": 12,
                "Sell_Price6": 12,
                "Sell_Price7": 0,
                "Sell_Price8": 0,
                "Sell_Price9": 0
            }
        ]
    }
}

It is possible to use simple filtering on resources by passing key pair values for field names and values. Simply pass the field you wish to filter on and the value you wish to find. Please see the individual resources for details of fields which filters can be used with. For more complex queries please see Query for details. Example below is from the stock resource.

Property	Example	Description
Count	URL/api/stock?barcode=5060395910013	Returns all stock with a Barcode equal to 5060395910013.

Ordering

https://URL/api/stock?order_by=season;> Will return all stock ordered by season.

https://URL/api/stock?order_by=season;colour;< Will return all stock ordered by season and then by colour in reverse order.

It is possible to use perform server side ordering on the returned data. Simply use the order_by keyword followed by the field you wish to order by. By default the order will be performed in alphabetic, numerical or date order dependent on the field type. If the sort order indicator is used > or < you can control the order.

Multiple order fields can be combined to carry out multi level sorting of the returned data.

Fields

https://URL/api/stock?fields=barcode,colour,size Will return all stock with just the specified fields.

{
    "response": {
        "Page": 1,
        "PageCount": 2301,
        "RecordsSent": 1,
        "RecordsFound": 2301,
        "Stock": [
            {
                "SKUSize": "A0000001010A",
                "Colour": "OFF WHITE",
                "Size": "S",
                "Barcode": "5060395910013"
            }
        ]
    }
}

Using the "fields" key word you can specify which fields you wish to return from the resource. Some resources will also return mandatory fields.

Exclude

https://URL/api/stock?exclude=@price@,@size@,@brand@,@code&pagesize=1 Will return all stock with the specified fields ommitted.

{
    "response": {
        "Page": 1,
        "PageCount": 2301,
        "RecordsSent": 1,
        "RecordsFound": 2301,
        "Stock": [
            {
                "SKU": "A0000001010",
                "SKUSize": "A0000001010A",
                "Colour": "OFF WHITE",
                "Style": "A0000001",
                "Article": "FLORAL 1",
                "In_Stock": 58,
                "Demand": 0,
                "Supply": 2,
                "Available": 60,
                "Web_Description": "",
                "Product_Group": "Long Sleeve Shirts",
                "Season": "AW16",
                "Cost_Centre": "",
                "Origin": "China",
                "Fabric_Content": "100% Cotton",
                "Stock_Change_TS": "20170320153348",
                "Discontinued": false
            }
        ]
    }
}

Using the "exclude" key word you can exclude fields and linked resources from the returned data. Some resources may ignore a call to exclude mandatory fields. Exclude will also support the @ wildcard to exclude a group of fields with a similar name pattern.

Examples:

https://URL/api/stock?exclude=@price@,@size@,@brand@,@code&pagesize=1

This will remove all properties that contain 'price', 'size' or end in 'code'. Notice the Key field SKUSize has not been removed as this is a mandatory field.

Query

https://URL/api/stock with request containing a query object array

{
    "query": [
        {
            "field": "sell_price1",
            "operator": "<=",
            "value": "12"
        },
        {
            "conjunction": "&",
            "field": "size",
            "operator": "=",
            "value": "s"
        }
    ]
}

Sometimes simple filtering is not sufficient to return complex selection requirements. In these cases you can use the request query object to carry out more complex queries on the resource. The example code finds all stock items where the value of sell_price1 is less than or equal to 12 and the size is equal to "S".

The query object can be used in conjunction with filtering but be aware that the query object will be applied first and then any filtering will be carried out on the subsequent selection.

Property	Example	Description
field	size	Should be any valid field in the resource model.
operator	=	Valid values are =, #, <=, >=, >, <
value	"S"	Values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False.
conjunction	&	Valid values are '&' = AND, '

Query Selection

https://URL/api/stock with request containing a query object array and a queryselection array

{
    "query": [
        {
            "conjunction": "&",
            "field": "size",
            "operator": "=",
            "value": "s"
        },
        {
            "conjunction": "|",
            "field": "size",
            "operator": "=",
            "value": "m"
        }
    ],
    "queryselection": [
        {
            "field": "sell_price1",
            "operator": "<=",
            "value": "12"
        }
    ]
}

While our developers were working on a project using the REST services they realised that sometimes more complex queries are more easily broken up by doing a query and then a further query on th resulting selection. This can be achieved by passing queryselection in the same way as query but as a seperate array of arguments.

The queryselection object will be performed after any query and before any filters.

Property	Example	Description
field	size S	hould be any valid field in the resource model.
operator	=	Valid values are =, #, <=, >=, >, <
value	"S"	Values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False.
conjunction	&	Valid values are '&' = AND, '

Query With Array

https://URL/api/concessionstock with request containing a querywitharray

{
    "querywitharray": {
            "field": "store_code",
            "values": [
                "TSMeado",
                "TSOxfor"                    
            ]
        }
}

The query with array object allows for the passing of a field and an array of values. This will return a selection that matches the elements of the arrays.

The querywitharray should not be used in conjunction with the query object but can be used before either the queryselection or queryselectionwitharray objects.

Property	Example	Description
field	store_code	Should be any valid field in the resource model.
operator	=	Valid values are =, #, <=, >=, >, <
values	[]	Array of values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False.

Query Selection With Array

https://URL/api/concessionstock with request containing a queryselectionwitharray

{
    "queryselectionwitharray": {
            "field": "store_code",
            "values": [
                "TSMeado",
                "TSOxfor"                    
            ]
        }
}

The query selection with array object allows for the passing of a field and an array of values. This will return a selection that matches the elements of the arrays.

The queryselectionwitharray should be used sfter the query or querywitharray objects and can be used in conjunction with the queryselection object but can be used before either the queryselection or queryselectionwitharray objects. The queryselectionwitharray object will be performed after any query and before any filters.

Property	Example	Description
field	store_code	Should be any valid field in the resource model.
operator	=	Valid values are =, #, <=, >=, >, <
values	[]	Array of values should be consistent with the data type of the field you are searching in. Text values are case insensitive. Dates should be in the format 2017-06-27. Booleans should be expressed as True or False.

Query using POST

https://URL/api/stock/query pass queryObject as the request body. If using POST specify the additional query parameter.

When testing the REST API with jQuery and ajax it became apparent that some environments restrict the sending of a body with a GET request. Following this we went through various steps to understand how to allow the query functionality whilst keeping our rules simple. Looking at other environments they seem to have got round the restriction by using a POST. Whilst this is not elegant it does work.

OPTION 1 - USE GET with BODY (if allowed from your environment) https://URL/api/stock pass queryObject as the body defined as one of the above object formats.

OPTION 2 - USE POST method https://URL/api/stock/query where query is passed as an additional parameter similar to how count works.

In this usage the client can send a body payload because POST is used but the server will treat it like a GET and process the request as normal using the request body.

Q. Why can I not use get and just pass a query key pair parameter with the URL? A. We did consider this as an option but quickly hit the limitations of the text which can be sent as part of the URL.

Authentication​

Response Details​

Request Pagination​

Count​

Filtering​

Ordering​

Fields​

Exclude​

Query​

Query Selection​

Query With Array​

Query Selection With Array​

Query using POST​