Explanation

Expanding Objects

In order to limit the size of the responses and the number of API calls to the server, UltraCart supports expanding certain objects through the _expand query parameter. The best example of expansion is the item object, because items contain a large amount of data. Often programs want to query an item, but only a portion of it, make a change, and then update the item. REST expansion lets you indicate how you want 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.

note

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.

Example

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,
            "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
            }]
        }]
    }
}

Was this page helpful?

Example​

Example