Filtering documentation needs some clarification and a running example

[leper]

What does It is important to understand that when using filters in your request, the filters you specify will only be applied to the bottom-level columns. actually mean?

What is the bottom-level, what are columns? Are you talking about the top level entries in the JSON object (unlikely, at least given my tests, though that might just be broken)? Are you talking about the most deeply nested entries in that JSON, and if yes, what if there are multiple entries (with different paths) at the same depth?

It would be nice to be able to specify exactly what one wants to filter. So something like ?name=data.*.id:1234, so one can do more specific filtering.

At the very least some actual test data and examples and responses for those in the documentation would help.

[Patskimoto]

Agreed and this explanation will be improved. What it meant was that you can only filter by the bottom level parameters is that nested objects in the response cannot be filtered by at the moment. As an example, this is what can be filtered by:

{
  "data": [
    {
      "id": 2, // filterable
      "game_id": 2, // filterable
      "submitted_by": {
        "id": 1,
        "name_id": "xant",
        "username": "XanT",
        "date_online": 1509922961,
        "avatar": {
          "filename": "masterchief.jpg",
          "original": "https://media.mod.io/images/members/1/1/1/masterchief.jpg"
        },
        "timezone": "Australia/Brisbane",
        "language": "en",
        "profile_url": "https://mod.io/members/xant"
      },
      "date_added": 1492564103, // filterable
      "date_updated": 1499841487, // filterable
      "date_live": 1499841403, // filterable
      "logo": {
        "filename": "IMG_20170409_222419.jpg",
        "original": "https://media.mod.io/images/mods/1/1/2/IMG_20170409_222419.jpg",
        "thumb_320x180": "https://media.mod.io/cache/images/mods/1/1/2/thumb_320x180/IMG_20170409_222419.jpg",
        "thumb_640x360": "https://media.mod.io/cache/images/mods/1/1/2/thumb_640x360/IMG_20170409_222419.jpg",
        "thumb_1280x720": "https://media.mod.io/cache/images/mods/1/1/2/thumb_1280x720/IMG_20170409_222419.jpg"
      },
      "homepage": "https://www.rogue-hdpack.com/", // filterable
      "name": "Rogue Knight HD Pack", // filterable
      "name_id": "rogue-knight-hd-pack", // filterable
      "summary": "It's time to bask in the glory of beautiful 4k textures!", // filterable
      "description": "<h2>About</h2><p>Rogue HD Pack does exactly what you thi...", // filterable
      "metadata_blob": "rogue,hd,high-res,4k,hd textures", // filterable
      "profile_url": "https://rogue-knight.mod.io/rogue-knight-hd-pack", // filterable
      "modfile": {
        "id": 2,
        "mod_id": 2,
        "date_added": 1499841487,
        "date_scanned": 1499841487,
        "virus_status": 0,
        "virus_positive": 0,
        "virustotal_hash": "f9a7bf4a95ce20787337b685a79677cae2281b83c63ab0a25f091407741692af-1508147401",
        "filesize": 15181,
        "filehash": {
          "md5": "2d4a0e2d7273db6b0a94b0740a88ad0d"
        },
        "filename": "rogue-knight-v1.zip",
        "version": "1.3",
        "changelog": "VERSION 1.3 -- Changes -- Fixed critical castle floor bug.",
        "download_url": "https://mod.io/mods/file/2/c489a0354111a4d76640d47f0cdcb294"
      },
      "media": {
        "youtube": [
          "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
        ],
        "sketchfab": [
          "https://sketchfab.com/models/ef40b2d300334d009984c8865b2db1c8"
        ],
        "images": [
          {
            "original": "https://media.mod.io/images/mods/1/1/2/IMG_20170409_222419.jpg",
            "thumb_320x180": "https://media.mod.io/cache/images/mods/1/1/2/thumb_1020x2000/IMG_20170409_222419.jpg",
            "filename": "IMG_20170409_222419.jpg"
          }
        ]
      },
      "rating_summary": {
        "total_ratings": 1230,
        "positive_ratings": 1047,
        "negative_ratings": 183,
        "percentage_positive": 91,
        "weighted_aggregate": 87.38,
        "display_text": "Very Positive"
      },
      "tags": [
        {
          "name": "Unity",
          "date_added": 1499841487
        }
      ]
    },
    {
        ...
    }
  ],
  "cursor_id": 60,
  "prev_id": 30,
  "next_id": 160,
  "result_count": 100
}

I agree with your suggestion that filtering nested objects by the * notation would be ideal, as mentioned in another thread this is not currently supported however we are investigating implementing it.

[leper]

Ah, I'd have called that "properties of the data elements", or top-level (though not quite), but certainly not bottom level.

Thanks for the explanation, that cleared things up.

[intenscia]

How does this sound:

mod.io has powerful filtering available to assist you when making requests to the API. You can filter on all columns in the parent object only. You cannot apply filters to columns in nested objects, so if a game contains a user object you cannot filter by the username column, but you can filter by the games name since the column resides in the parent object.

[leper]

Somewhat better. Though "nested objects" is still slightly fuzzy. I guess an example with comments // can be filtered on for everything on the correct level would help.

[intenscia]

I'll leave it as this for now, but we are working on ways to get better examples in the documentation - to help people better understand it.