Expanding Objects

In order to limit the size of the responses and the number of API calls to the server, UltraCart supports expanding of certains objects through the _expand query parameter. The best example of expansion is the item object because they contain a large amount of data. Often times programs want to query an item, but only a portion of it, make a change, and then update the item. REST expansion allows you to indicate how you want to the object expanded beyond the basic object on the retrieval request. This reduces the need to make additional API calls to fetch deeper information as most REST APIs require. Then on the update API calls, if the object is only partially expanded then only those portions of the object are updated. The rest of the object that exists on the server is left alone. Using REST expansion will:

• Make your REST API calls faster
• Reduce the bandwidth consumed by your API calls
• Provide simpler objects to work with

Each REST API that supports expansion will have the _expand parameter documented on the API call. The corresponding create/update REST APIs will handle receiving the partially expanded object without any special action on your part.

You will also see the exact same expansion syntax used on the _expand parameter is also used in our webhook configuration to specify the amount of expansion for the objects that you receive notices on.

Here is an example of a real-world _expand parameter from a wordpress plugin.

_expand=pricing,shipping.distribution_centers,content.multimedia.thumbnails[filter(100,100,"png", true),filter(360,360, "png", true)]

The sample expansion above tells the system that the call is interested in:

• pricing
• shipping
• distribution_centers (this contains the inventory information)
• content
  • multimedia
    • thumbnails (filtered to 100x100 square PNGs and 360x360 square PNGs)

Basic Item Response

{
    "merchant_item_oid": 875851,
    "merchant_id": "DEMO",
    "merchant_item_id": "Baseball Bat",
    "description": "Wood Baseball Bat",
    "description_translated_text_instance_oid": 649867,
    "last_modified_dts": "2016-08-11T16:14:46-04:00",
    "creation_dts": "2009-01-14T18:30:42-05:00"
}

Expanded Item Response

{
    "merchant_item_oid": 875851,
    "merchant_id": "DEMO",
    "merchant_item_id": "Baseball Bat",
    "description": "Wood Baseball Bat",
    "description_translated_text_instance_oid": 649867,
    "last_modified_dts": "2016-08-11T16:14:46-04:00",
    "creation_dts": "2009-01-14T18:30:42-05:00",
    "pricing": {
        "cost": 5.50
    },
    "shipping": {
        "distribution_centers": [{
            "distribution_center_oid": 29522,
            "distribution_center_code": "DFLT",
            "inventory_level": 4,
            "handles": true,
            "allocated_to_placed_orders": 2,
            "allocated_to_shopping_carts": 0,
            "available_to_allocate": 2
        }]
    },
    "content": {
        "view_url": "http://www.testajax.com/catalog/DEMO/products/facebook/fb-single/Baseball Bat.html",
        "multimedia": [{
            "merchant_item_multimedia_oid": 239393,
            "file_name": "baseballbat.jpg",
            "description": "Baseball Bat",
            "url": "//secure.ultracart.com/itemmultimedia/DEMO/BASEBALL BAT/baseballbat.jpg",
            "type": "Image",
            "code": "default",
            "width": 108,
            "height": 120,
            "cloud_url": "https://s3.amazonaws.com/ultracart/im/E5DECF2DBFEDB40123A559FCAC631600?AWSAccessKeyId\u003d0P4TXH5AKGYC8WHDZFG2\u0026Expires\u003d1472837012\u0026Signature\u003dZ6mQqdhUWl3g1kbD%2B4wTT1AWvRc%3D",
            "cloud_url_expiration": "2016-09-02T13:23:32-04:00",
            "thumbnails": [{
                "height": 100,
                "width": 100,
                "http_url": "http://ultracartthumbs.s3.amazonaws.com/1363101689475/DEMO/0/1/100-100-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "https_url": "https://s3.amazonaws.com/ultracartthumbs/1363101689475/DEMO/0/1/100-100-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "square": true
            }, {
                "height": 360,
                "width": 360,
                "http_url": "http://ultracartthumbs.s3.amazonaws.com/1472069542543/DEMO/0/1/360-360-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "https_url": "https://s3.amazonaws.com/ultracartthumbs/1472069542543/DEMO/0/1/360-360-01C192A2E7695865D44C6C51ECE91A29.jpg",
                "square": true
            }]
        }]
    }
}