Multiable API for ImportersBridge

The following is a detailed description of the API for ImportersBridge. Please, adhere diligently to the structure and naming conventions so as to avoid future confusion.

Preface

As has been discussed already, we need to rethink the entire concept of the ERP connectivity between the ImportersBridge website, and the Multiable ERP. It appears that this has been assumed that we would be using the ERP for live connectivity, that is, to be able to connect and request items and data on demand.

This isn't the case!

As has been already been mentioned in the email exchange, we do not intend to use the Multiable ERP as a live inventory, but rather as a repository for the data, to be stored, managed, and then shared with the website in bulk.

Throughout the operation of the website, it will rely entirely on its own database to display information to the end user, which is why we're going to need to be able to connect periodically, and collect information from the ERP, to add new items, and to synchronize the website with the Multiable data.

To this very end, we need the API to accommodate this kind of functionality. The following is the specification of the API the way we need it.

Please, go over this document, and let me know how we can proceed with it.

Item

JSON structure

The following is an items structure. This is exactly how each item should return, when requested.

		

{
	"style_data": { //This object will contain the global style information. 
		"loka_id": "FIX000581", 
		"item_name": "7.5*8 PAPER CUP", // Item name in English, as it appears for the style. 
		"qtyCtn": 300 // Item per container
	},
	"clients": { 
		// This is an ARRAY! It should contain a list of all the clients with the key being the client name/code.
		// As you may see, for Deltafix the code is DFX. This should serve as the key of the array object for each company
		"DFX": {
			// Each one of these is an object containing the client information.
			"client_code": "DFX",
			"client_name": "Deltafix",
			"item_name": "\u05d1\u05d3\u05d9\u05e7\u05d4 1", // This is the item name PER client. So, for deltafix the name will be in Hebrew
			"item_description": "Description here", // Same here. This is the item description, as presented specifically doe Deltafix
			"currency": "S",
			"wBasicUP": 10,
			"wVIPUP": 5,
			"wVVIPUP": 2
		},
		"GGF": {
			// This is another company object. The name is completely made up for illustration purposes. 
			"client_code": "GGF",
			"client_name": "GoodGameFragment",
			"item_name": "Test 1",
			"item_description": "Description here ttt",
			"currency": "D",
			"wBasicUP": 3,
			"wVIPUP": 2,
			"wVVIPUP": 1
		}
	},
	"colors": {
		// This is another associative array. This will simply list the colors that this item has. They're not connected to anything. 
		// Just a list of colors that this style has.
		// Again, notice that it's an associative array w with the English color name as the array key.
		"DEFAULT": {
			"titleHEB": "\u05e8\u05d2\u05d9\u05da",
			"titleENG": "DEFAULT"
		},
		"GREEN": {
			"titleHEB": "\u05d9\u05e8\u05d5\u05e7",
			"titleENG": "GREEN"
		}
	},
	"sizes": {
		// The same as colors
		"XL": {
			"titleHEB": "XL",
			"titleENG": "XL"
		},
		"L": {
			"titleHEB": "L",
			"titleENG": "L"
		}
	},
	"item_specifics": [
		// This is where colors and sizes are connected into an actual item. 
		// Each item within the style may consist of a combination of colors and sizes. 
		// So, every record here is a single item, along with the quantity available
		{
			"color": "GREEN",
			"size": "XL",
			"quantity": 100
		},
		{
			"color": "GREEN",
			"size": "L",
			"quantity": 50
		},
		{
			"color": "DEFAULT",
			"size": "L",
			"quantity": 500
		}
	],
	"categories": {
		// The way the categories are organized is very similar to the way it currently works.
		// I only ask that you follow these exact naming conventions.
		
		// As a refresher - Each item is assigned into a single category, but also to a list of attributes. 
		// Attributes themselves are grouped by a parent attribute which lists them
		"titleHEB": "\u05d1\u05d3\u05d9\u05e7\u05d4! 1",
		"titleENG": "Test category 1",
		"category_id": "PTY",
		"attributes": {
			"MMT": {
				"titleHEB": "\u05d7\u05d5\u05de\u05e8 \u05e2\u05d9\u05e7\u05e8\u05d9",
				"titleENG": "Main Material",
				"category_id": "MMT",
				"sub_categories": {
					"MMT080": {
						"titleHEB": "\u05e7\u05e8\u05d8\u05d5\u05df",
						"titleENG": "Cardboard",
						"sub_category_id": "MMT080"
					},
					"MMT081": {
						"titleHEB": "\u05e0\u05d9\u05d9\u05e8",
						"titleENG": "Paper",
						"sub_category_id": "MMT081"
					}
				}
			}
		}
	}
}

		

Requests

I would like to be able to query the Multiable server in a variety of ways.

I'd like to be able to do the following:

  1. Get a particular item or items.
  2. Get the entire list of item IDs.
  3. Get the entire list of items (just like the above, except it should output the entire list of available items, with all their information).
  4. To receive a list of all items that have been edited (or added) between two dates, or from a particular date up until now.

1.

Currently, if I want to receive information about a particular item, I can do the following: make a reqyest to the following address items/main/-ITEM_ID- and receive a response in form of a json, containing a single item.

What I would like to be able to do is query this address with one or more IDs and receive these items in one request. So, for example if I make the following request

items/main/00000456,00000112,00000998
I should receive the following response:

			
{
    "00000456": {
        "style_data": {
            "loka_id": "00000456",
            "item_name": "7.5*8 PAPER CUP",
            "qtyCtn": 300
        },
        "clients": {
            "DFX": {
                "client_code": "DFX",
                "client_name": "Deltafix",
                "item_name": "\u05d1\u05d3\u05d9\u05e7\u05d4 1",
                "item_description": "Description here",
                "currency": "S",
                "wBasicUP": 10,
                "wVIPUP": 5,
                "wVVIPUP": 2
            },
            "GGF": {
                "client_code": "GGF",
                "client_name": "GoodGameFragment",
                "item_name": "Test 1",
                "item_description": "Description here ttt",
                "currency": "D",
                "wBasicUP": 3,
                "wVIPUP": 2,
                "wVVIPUP": 1
            }
        },
        "colors": {
            "DEFAULT": {
                "titleHEB": "\u05e8\u05d2\u05d9\u05da",
                "titleENG": "DEFAULT"
            },
            "GREEN": {
                "titleHEB": "\u05d9\u05e8\u05d5\u05e7",
                "titleENG": "GREEN"
            }
        },
        "sizes": {
            "XL": {
                "titleHEB": "XL",
                "titleENG": "XL"
            },
            "L": {
                "titleHEB": "L",
                "titleENG": "L"
            }
        },
        "item_specifics": [
            {
                "color": "GREEN",
                "size": "XL",
                "quantity": 100
            },
            {
                "color": "GREEN",
                "size": "L",
                "quantity": 50
            },
            {
                "color": "DEFAULT",
                "size": "L",
                "quantity": 500
            }
        ],
        "categories": {
            "titleHEB": "\u05d1\u05d3\u05d9\u05e7\u05d4! 1",
            "titleENG": "Test category 1",
            "category_id": "PTY",
            "attributes": {
                "MMT": {
                    "titleHEB": "\u05d7\u05d5\u05de\u05e8 \u05e2\u05d9\u05e7\u05e8\u05d9",
                    "titleENG": "Main Material",
                    "category_id": "MMT",
                    "sub_categories": {
                        "MMT080": {
                            "titleHEB": "\u05e7\u05e8\u05d8\u05d5\u05df",
                            "titleENG": "Cardboard",
                            "sub_category_id": "MMT080"
                        },
                        "MMT081": {
                            "titleHEB": "\u05e0\u05d9\u05d9\u05e8",
                            "titleENG": "Paper",
                            "sub_category_id": "MMT081"
                        }
                    }
                }
            }
        }
    },
    "00000112": {
        "style_data": {
            "loka_id": "00000112",
            "item_name": "7.5*8 PAPER CUP",
            "qtyCtn": 300
        },
        "clients": {
            "DFX": {
                "client_code": "DFX",
                "client_name": "Deltafix",
                "item_name": "\u05d1\u05d3\u05d9\u05e7\u05d4 1",
                "item_description": "Description here",
                "currency": "S",
                "wBasicUP": 10,
                "wVIPUP": 5,
                "wVVIPUP": 2
            },
            "GGF": {
                "client_code": "GGF",
                "client_name": "GoodGameFragment",
                "item_name": "Test 1",
                "item_description": "Description here ttt",
                "currency": "D",
                "wBasicUP": 3,
                "wVIPUP": 2,
                "wVVIPUP": 1
            }
        },
        "colors": {
            "DEFAULT": {
                "titleHEB": "\u05e8\u05d2\u05d9\u05da",
                "titleENG": "DEFAULT"
            },
            "GREEN": {
                "titleHEB": "\u05d9\u05e8\u05d5\u05e7",
                "titleENG": "GREEN"
            }
        },
        "sizes": {
            "XL": {
                "titleHEB": "XL",
                "titleENG": "XL"
            },
            "L": {
                "titleHEB": "L",
                "titleENG": "L"
            }
        },
        "item_specifics": [
            {
                "color": "GREEN",
                "size": "XL",
                "quantity": 100
            },
            {
                "color": "GREEN",
                "size": "L",
                "quantity": 50
            },
            {
                "color": "DEFAULT",
                "size": "L",
                "quantity": 500
            }
        ],
        "categories": {
            "titleHEB": "\u05d1\u05d3\u05d9\u05e7\u05d4! 1",
            "titleENG": "Test category 1",
            "category_id": "PTY",
            "attributes": {
                "MMT": {
                    "titleHEB": "\u05d7\u05d5\u05de\u05e8 \u05e2\u05d9\u05e7\u05e8\u05d9",
                    "titleENG": "Main Material",
                    "category_id": "MMT",
                    "sub_categories": {
                        "MMT080": {
                            "titleHEB": "\u05e7\u05e8\u05d8\u05d5\u05df",
                            "titleENG": "Cardboard",
                            "sub_category_id": "MMT080"
                        },
                        "MMT081": {
                            "titleHEB": "\u05e0\u05d9\u05d9\u05e8",
                            "titleENG": "Paper",
                            "sub_category_id": "MMT081"
                        }
                    }
                }
            }
        }
    },
    "00000998": {
        "style_data": {
            "loka_id": "00000998",
            "item_name": "7.5*8 PAPER CUP",
            "qtyCtn": 300
        },
        "clients": {
            "DFX": {
                "client_code": "DFX",
                "client_name": "Deltafix",
                "item_name": "\u05d1\u05d3\u05d9\u05e7\u05d4 1",
                "item_description": "Description here",
                "currency": "S",
                "wBasicUP": 10,
                "wVIPUP": 5,
                "wVVIPUP": 2
            },
            "GGF": {
                "client_code": "GGF",
                "client_name": "GoodGameFragment",
                "item_name": "Test 1",
                "item_description": "Description here ttt",
                "currency": "D",
                "wBasicUP": 3,
                "wVIPUP": 2,
                "wVVIPUP": 1
            }
        },
        "colors": {
            "DEFAULT": {
                "titleHEB": "\u05e8\u05d2\u05d9\u05da",
                "titleENG": "DEFAULT"
            },
            "GREEN": {
                "titleHEB": "\u05d9\u05e8\u05d5\u05e7",
                "titleENG": "GREEN"
            }
        },
        "sizes": {
            "XL": {
                "titleHEB": "XL",
                "titleENG": "XL"
            },
            "L": {
                "titleHEB": "L",
                "titleENG": "L"
            }
        },
        "item_specifics": [
            {
                "color": "GREEN",
                "size": "XL",
                "quantity": 100
            },
            {
                "color": "GREEN",
                "size": "L",
                "quantity": 50
            },
            {
                "color": "DEFAULT",
                "size": "L",
                "quantity": 500
            }
        ],
        "categories": {
            "titleHEB": "\u05d1\u05d3\u05d9\u05e7\u05d4! 1",
            "titleENG": "Test category 1",
            "category_id": "PTY",
            "attributes": {
                "MMT": {
                    "titleHEB": "\u05d7\u05d5\u05de\u05e8 \u05e2\u05d9\u05e7\u05e8\u05d9",
                    "titleENG": "Main Material",
                    "category_id": "MMT",
                    "sub_categories": {
                        "MMT080": {
                            "titleHEB": "\u05e7\u05e8\u05d8\u05d5\u05df",
                            "titleENG": "Cardboard",
                            "sub_category_id": "MMT080"
                        },
                        "MMT081": {
                            "titleHEB": "\u05e0\u05d9\u05d9\u05e8",
                            "titleENG": "Paper",
                            "sub_category_id": "MMT081"
                        }
                    }
                }
            }
        }
    }
}
			
			

Notice that the response contains 3 items, in an array, and the index of each and every one of them is the style number

Please, also note that just for the sake of demonstration, I've taken the same item and duplicated it 3 times, only changing the style number

Important - In some cases, you may encounter an object which I called array but is in fact an object. For example:

			
    "clients": {
            "DFX": {
                "client_code": "DFX",
                "client_name": "Deltafix",
                "item_name": "\u05d1\u05d3\u05d9\u05e7\u05d4 1",
                "item_description": "Description here",
                "currency": "S",
                "wBasicUP": 10,
                "wVIPUP": 5,
                "wVVIPUP": 2
            },
            "GGF": {
                "client_code": "GGF",
                "client_name": "GoodGameFragment",
                "item_name": "Test 1",
                "item_description": "Description here ttt",
                "currency": "D",
                "wBasicUP": 3,
                "wVIPUP": 2,
                "wVVIPUP": 1
            }
        }
			
		

I will be treating it as an array since it has a key. An associative key, but a key.

This is very important, because my own code will, when encountering this part, will attempt to iterate over the stuff that's inside "clients". So, even if there's only a single item, it will be treated as a list of items containing a single item.

2.

Nothing new here. Just like today, I want to be able to retrieve the entire list of IDs

3.

Just like suggested, I want to be able to retrieve the entire list of all the items available. Not just the IDs as I presently can, but all the items along with their information
Please, take a look at the above example (in section 1) how it should return. Basically, it should be an entire JSON object with all the respective items and their data

4.

Just like in sections 1 and 3, I want to be able to receive multiple items, but based on dates. So, if for example, instead of specifying a particular item or items, I specify a date or a date range, I want to be able to receive all the items that had their information modified within these dates

So, for example if I try to request the following address: items/main/2017-03-01 00:00:00 I should receive all the items that had been modified in some way, from the date specified all the way up til now.
Also, the ability to specify an end date as well.

Users (subclients)

I should be able to download a list of all the users currently available in the ERP. The following is the structure of the user json

			
			

{
    "loka_id": "2342342", // Some sort of a unique identifier on the Multiable ERP
    "email": "moti@example.com", // Email address. Currently, as far as I know, this field is missing on Multiable. Needs to be added.
    "fullname": "Moti Benmoti", // Either fullname, or two fields first_name and last_name, whichever is closer to what you currently have.
    "client": "DFX", // The client that this cubclient belongs to. 
    "position": "VVIP", // Basic/VIP/VVIP. I don't care about the specific options for these three. Whatever you can send to identify a user's status
    "items": [
		// This is the list of items that the user is allowed to see/access. 
        "00023423234234",
        "00023423111",
        "00023423324",
        "00023421215",
        "00022364g",
        "000234239",
        "0002342311",
        "00023422"
    ],
    "categories": [
    // Similar to "items", but for categories.
        "PRY",
        "KTC",
        "HSD",
        "BNS",
        "AGE",
        "JJG",
        "BVV",
        "VVV"
    ]
}
			
			
			
		

The users object is a lot simpler. Please, adhere to the naming convention and structure as outlined above. Please, also note the comments.

Requests

Just like for the items methods, I would like to query the multiable ERP in various ways, for different results

  1. Get a particular user or users.
  2. Get the entire list of user IDs.
  3. Get the entire list of users (just like the above, except it should output the entire list of available users, with all their information).
  4. To receive a list of all users that have been edited (or added) between two dates, or from a particular date up until now.

Without getting into details about each and every section because it's very similar to the 4 sections for items, just as a general comment, I want to be able to receive users, and their data in a single request. I should be able to request a list of all users, a list of all user IDs, a list of a particular user or users by supplying a list of user IDs. This should result in a detailed list of the users specified.

As for the fourth section, just like for "items", I'd like to query the ERP for all the users that have been added or modified in a fixed period of time. So, if I supply a certain date the ERP should return a list of all the users that have either been added or modified from this date til now, and just like with items, the ability to specify a date range (eg: from 2017-03-19 to 2017-03-25)

Also, please note that even though I only use a date in my examples, it is important for both users and items that I should be able specify time as well as a date, not just date. This is for more frequent queries.

Wishlist:

Things that aren't strictly necessary but would be great to have.

While this isn't strictly necessary, it would be of extreme benefit if we could have the Multiable ERP initiate requests back to us, in some circumstances.

For example, if you could setup an event on your system that would fire whenever an item has been modified, which would contact the web service first. That way, we'd be informed of changes that are taking place on the ERP without having to constantly change. I will not elaborate on this now, but if this is possible, please let me know.