Optimizing response sizes

When requesting an object from the API, by default, you will receive a response that contains all of the data for that object. This response will also include links to other API endpoints related to that object, and metadata about the parameters accepted by the current request method.

Various options are available which allow you to customize which parts of the response are sent, which can reduce the number of bytes your application downloads.

Summary

Name Value Description
_filter A comma-separated list of data field names Removes all data fields except the ones named
_filteruri A comma-separated list of URI names Removes all URI fields except the ones named
_shorturis Just needs to be present Removes metadata from Uris section
_verbosity 1, 2, or 3 Controls the quantity of metadata

If you want to use these options on expansions, you will need the advanced expansion configuration syntax.

_filter and _filteruri

A filter is a query argument that allows you to specify the fields you would like to be included in the response. The SmugMug API supports filtering on both the data fields in the response, as well as the linked URIs. This can be done by providing the query argument _filter or _filteruri with a comma separated list of the fields that should remain in the response. If no value is provided, all fields or URIs will be removed.

Let's look at an example of _filter and _filteruri in action.

Unfiltered request:

GET /api/v2/user/cmac!profile HTTP/1.1
Host: www.smugmug.com
Accept: application/json

Unfiltered response:

{
    "Request": {
        "Version": "v2",
        "Method": "GET",
        "Uri": "/api/v2/user/cmac!profile"
    },
    "Options": {
        "MediaTypes": [
            "application/json",
            "application/vnd.php.serialized",
            "application/x-msgpack",
            "application/xml",
            "text/html",
            "text/csv"
        ],
        "Methods": [
            "OPTIONS",
            "GET"
        ]
    },
    "Response": {
        "Uri": "/api/v2/user/cmac!profile",
        "UriDescription": "User's profile information",
        "EndpointType": "UserProfile",
        "Locator": "UserProfile",
        "LocatorType": "Object",
        "UserProfile": {
            "Uri": "/api/v2/user/cmac!profile",
            "UriDescription": "User's profile information",
            "BioText": "co-founder of SmugMug.  Lover of family, photos, triathlon, and health.",
            "Facebook": "",
            "Twitter": "",
            "GooglePlus": "",
            "Uris": {
                "BioImage": {
                    "Uri": "/api/v2/user/cmac!bioimage",
                    "UriDescription": "User BioImage",
                    "EndpointType": "BioImage",
                    "Locator": "BioImage",
                    "LocatorType": "Object"
                },
                "User": {
                    "Uri": "/api/v2/user/cmac",
                    "UriDescription": "User By Nickname",
                    "EndpointType": "User",
                    "Locator": "User",
                    "LocatorType": "Object"
                }
            }
        },
        "Timing": {
            "Total": {
                "time": 0.03028,
                "cycles": 1,
                "objects": 0
            }
        }
    },
    "Code": 200,
    "Message": "Ok"
}

Filtered request:

GET /api/v2/user/cmac!profile?filter=BioText,Facebook&filteruri=User HTTP/1.1
Host: www.smugmug.com
Accept: application/json

Filtered response:

{
    "Request": {
        "Version": "v2",
        "Method": "GET",
        "Uri": "/api/v2/user/cmac!profile?filter=BioText,Facebook&filteruri=User"
    },
    "Options": {
        "MediaTypes": [
            "application/json",
            "application/vnd.php.serialized",
            "application/x-msgpack",
            "application/xml",
            "text/html",
            "text/csv"
        ],
        "Methods": [
            "OPTIONS",
            "GET"
        ]
    },
    "Response": {
        "Uri": "/api/v2/user/cmac!profile?filter=BioText,Facebook&filteruri=User",
        "UriDescription": "User's profile information",
        "EndpointType": "UserProfile",
        "Locator": "UserProfile",
        "LocatorType": "Object",
        "UserProfile": {
            "BioText": "co-founder of SmugMug.  Lover of family, photos, triathlon, and health.",
            "Facebook": "",
            "Uris": {
                "User": {
                    "Uri": "/api/v2/user/cmac",
                    "UriDescription": "User By Nickname",
                    "EndpointType": "User",
                    "Locator": "User",
                    "LocatorType": "Object"
                }
            }
        },
        "Timing": {
            "Total": {
                "time": 0.13315,
                "cycles": 1,
                "objects": 0
            }
        }
    },
    "Code": 200,
    "Message": "Ok"
}

_shorturis

Another option to reduce the size of your API responses is the _shorturis option. If this parameter is present in an API request, the URI section of the response object will be trimmed down so that each entry is just a key-value pair of name to URI. This removes all metadata about the URI from the response.

Below is an example of a URIs section with and without _shorturis.

Without _shorturis:

{
    "Uri": "/api/v2/user/cmac!profile",
    "UriDescription": "User's profile information",
    "BioText": "co-founder of SmugMug.  Lover of family, photos, triathlon, and health.",
    "Facebook": "",
    "Twitter": "",
    "GooglePlus": "",
    "Uris": {
        "BioImage": {
            "Uri": "/api/v2/user/cmac!bioimage",
            "UriDescription": "User BioImage",
            "EndpointType": "BioImage",
            "Locator": "BioImage",
            "LocatorType": "Object"
        },
        "User": {
            "Uri": "/api/v2/user/cmac",
            "UriDescription": "User By Nickname",
            "EndpointType": "User",
            "Locator": "User",
            "LocatorType": "Object"
        }
    }
}

With _shorturis:

{
    "Uri": "/api/v2/user/cmac!profile?shorturis=",
    "UriDescription": "User's profile information",
    "BioText": "co-founder of SmugMug.  Lover of family, photos, triathlon, and health.",
    "Facebook": "",
    "Twitter": "",
    "GooglePlus": "",
    "Uris": {
        "BioImage": "/api/v2/user/cmac!bioimage",
        "User": "/api/v2/user/cmac"
    }
}
<script src="https://gist.github.com/smugkarl/456ed46f4033b7d3d0e6.js?file=shorturisobject.json">

_verbosity

Parameter Effect
_verbosity=1 No Options section. This also implies _shorturis=, and removes a few metadata fields that appear in the Response section.
_verbosity=2 If the current request method has parameters, there will be an Options section listing those parameters, but the parameters of other request methods will not be included. This is the default verbosity level, except for OPTIONS requests.
_verbosity=3 An Options section will be included, and parameters will be listed for all request methods. This is the default verbosity level for OPTIONS requests.