When you simply MUST have album images

I thought it was worth drawing out the difference between the inc and mustInc parameters. These parameters are used to define metadata that should be included in responses for releases (albums, singles, EPs, compilations etc). The most common use is when requesting to include image metadata; URLs and resolutions.

inc is the older parameter and is used to describe data that should be included in a response. This is non-strict; if the data simply doesn't exist for a given album (say) then the album is still included in the response.

mustInc was added for when your simply must have a certain type of data! If you request mustInc=images, for example, albums without images will not be included in the response.

You use the differing parameters for different use cases. If you are just looking for any release information, the more the better, then use inc and you'll get more release results. inc is good for breadth. On the other hand, if there's a specific type of data you are looking for, for example cover art images, use mustInc, because you just aren't interested in releases without that type of data. I suppose you could say it is best for depth.

Let's take a look at how that affects results. Let's start with a simple query with neither of the parameters:

http://api.onemusicapi.com/20150623/release?user_key=...&title=LP1&artist=FKA+Twigs&maxResultCount=3

This gives us the releases of this album, with no images (as expected; also note I have removed the media data in these results to keep this post length down):

[
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2014",
        "genre": "Electronic",
        "media": [
            ...
        ],
        "score": 1
    },
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2014",
        "genre": "Electronic",
        "media": [
            ...
        ],
        "score": 1
    },
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2015",
        "genre": "Pop",
        "media": [
            ...
        ],
        "score": 1
    }
]

Now we'll add in inc=images:

http://api.onemusicapi.com/20150623/release?user_key=...&title=LP1&artist=FKA+Twigs&maxResultCount=3&inc=images

This gives us the same releases with images were they exist:

[
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2014",
        "genre": "Electronic",
        "media": [
            ...
        ],
        "images": [
            {
                "url": "http://api.onemusicapi.com/20150623/images/discogs/5971939/1407752064-1082",
                "width": "600",
                "height": "600"
            }
        ],
        "score": 1
    },
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2014",
        "genre": "Electronic",
        "media": [
            ...
        ],
        "images": [
            {
                "url": "http://api.onemusicapi.com/20150623/images/discogs/5978538/1408383580-7746",
                "width": "600",
                "height": "596"
            }
        ],
        "score": 1
    },
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2015",
        "genre": "Pop",
        "media": [
            ...
        ],
        "score": 1
    }
]

These are the same releases as before, but decorated with the image metadata where it exists. Note that the final release does not contain any image metadata. If we replace our parameter with mustInc=images then this release is replaced with a release that does have the image metadata:

http://api.onemusicapi.com/20150623/release?user_key=...&title=LP1&artist=FKA+Twigs&maxResultCount=3&mustInc=images

Gives us:

[
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2014",
        "genre": "Electronic",
        "media": [
            ...
        ],
        "images": [
            {
                "url": "http://api.onemusicapi.com/20150623/images/discogs/5971939/1407752064-1082",
                "width": "600",
                "height": "600"
            }
        ],
        "score": 1
    },
    {
        "title": "LP1",
        "artist": "FKA Twigs",
        "year": "2014",
        "genre": "Electronic",
        "media": [
            ...
        ],
        "images": [
            {
                "url": "http://api.onemusicapi.com/20150623/images/discogs/5978538/1408383580-7746",
                "width": "600",
                "height": "596"
            }
        ],
        "score": 1
    },
    {
        "title": "LP1",
        "artist": "FKA twigs",
        "year": "2014",
        "genre": "pop",
        "media": [
            ...
        ],
        "images": [
            {
                "url": "http://api.onemusicapi.com/20150623/images/caa/a50f9ba3-5891-4f22-b5da-edf84cc04b0c/7598730014.jpg",
                "width": "1200",
                "height": "1200"
            }
        ],
        "types": [
            "Album"
        ],
        "score": 1
    }
]

So we can see the final release being replaced with a release that does have images.

Hopefully that outlines the difference, and your use case applies to one or the other!

Thanks to marfis75 who made the the image above available for sharing.