Configuring expansions

Before reading this page, please make sure you are familiar with both expansions and filters.

An expansion is a lot like any other API response: it can include a variety of data fields and related endpoint links, and those related endpoints can be expanded further. But what if you want to specify filters or other options on a particular expansion? You can't do that with _expand. There is an alternative way to specify expansions which gives you increased control and flexibility: _config.

The value of _config is a JSON object, which makes it easy to express complex configuration data.

Consider this example:

GET /api/v2/user/cmac?_config=%7B%22filter%22%3A%5B%22NickName%22%5D%2C%22filteruri%22%3A%5B%22UserProfile%22%5D%2C%22expand%22%3A%7B%22UserProfile%22%3A%7B%22filter%22%3A%5B%22BioText%22%5D%2C%22filteruri%22%3A%5B%22BioImage%22%5D%2C%22expand%22%3A%7B%22BioImage%22%3A%7B%22filter%22%3A%5B%5D%2C%22filteruri%22%3A%5B%22LargestImage%22%5D%2C%22expand%22%3A%7B%22LargestImage%22%3A%7B%22filter%22%3A%5B%22Url%22%5D%2C%22filteruri%22%3A%5B%5D%7D%7D%7D%7D%7D%7D%7D HTTP/1.1
Host: www.smugmug.com
Accept: application/json

In the example above, we see that the main request is for /api/v2/user/cmac, but a configuration has been supplied via the _config query parameter. It's tough to read that flattened and URL-encoded JSON, so here it is formatted for reading:

{
  "filter": ["NickName"],
  "filteruri": ["UserProfile"],
  "expand": {
    "UserProfile": {
      "filter": ["BioText"],
      "filteruri": ["BioImage"],
      "expand": {
        "BioImage": {
          "filter": [],
          "filteruri": ["LargestImage"],
          "expand": {
            "LargestImage": {
              "filter": ["Url"],
              "filteruri": []
            }
          }
        }
      }
    }
  }
}

You might also notice that this example includes both "filter" and "filteruri" at the top level. This is equivalent to supplying _filter and _filteruri query parameters. You might prefer to put all your filters in _config for consistency.

Query parameters for expanded responses

You might want to send a query parameter to an expanded response. In this example, we send the count parameter to control the number of albums returned:

GET /api/v2/node/zx4Fx?_config=%7B%22expand%22%3A%7B%22ChildNodes%22%3A%7B%22args%22%3A%7B%22count%22%3A25%7D%7D%7D%7D HTTP/1.1
Host: www.smugmug.com
Accept: application/json

Again, the JSON is easier to read when formatted:

{
  "expand": {
    "ChildNodes": {
      "args": {
        "count": 25
      }
    }
  }
}

Multi-args: getting one expansion multiple ways

You might want to expand the same related endpoint twice, with different query parameters each time. You can do this with "multiargs":

GET /api/v2/user/cmac!bioimage?_config=%7B%22expand%22%3A%7B%22ImageSizes%22%3A%7B%22expand%22%3A%7B%22ImageSizeCustom%22%3A%7B%22multiargs%22%3A%5B%7B%22width%22%3A500%2C%22height%22%3A500%7D%2C%7B%22width%22%3A900%2C%22height%22%3A900%7D%5D%7D%7D%7D%7D%7D HTTP/1.1
Host: www.smugmug.com
Accept: application/json

Again, the JSON is easier to read when formatted:

{
  "expand": {
    "ImageSizes": {
      "expand": {
        "ImageSizeCustom": {
          "multiargs": [
            {
              "width": 500,
              "height": 500
            },
            {
              "width": 900,
              "height": 900
            }
          ]
        }
      }
    }
  }
}

Note that "multiargs" is incompatible with "args". You can use "multiargs" at the top level to request the base endpoint multiple times, with different query parameters each time.