The current API (v1) hard-codes MD5 as the file hash. MD5 should be considered broken as collision attacks are relatively easy to do and do not take long.

To make the API easier to update/extend in the future (without even bumping the API version) having filehash be an object would be a lot nicer.

filehash: {
  md5: "abcd",
  sha256: "1234",
  sha3-512: "5689"
}

By just providing multiple hashes adding better hashes is easily doable, without breaking users of the API, and allowing nice updates. In case some hash is severely broken in the future one could even just drop that one from a new version of the API.

Currently the only checksum available for files is md5.

It would be nice if there's a checksum available that wasn't considered broken in the last century.

SHA-3 would be nice.

This field should register the date time on which the mod was made public for the first time.

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.

Since we will only support showing/downloading mods with a certain extension (due to being portable, somewhat similar to .umod for those that spent too much time with UT; actually just zip files that contain a mod.json file with some data we use, and the files for the mod), it would be nice to do that filtering when submitting the query.

It should be working (unless I'm missing something in the documentation), but the below example does not seem to do what it should.

curl --request GET 'https://api.mod.io/v1/games/57/mods?api_key=use_your_own&filename-lk=*.zip'
curl --request GET 'https://api.mod.io/v1/games/57/mods?api_key=use_your_own&filename-lk=*.zio'

Both return the same results (5, that is), while I would expect the second one to not return any result, as the only files present are some demo.zip files (which also does not seem to have the same md5sum as the filehash would indicate).

It would be nice if one could specify what parts of the "full" response one actually wants and thus not needing to transfer data that will not be used at all.

Currently we do a query curl --request GET 'https://api.mod.io/v1/games?api_key=use_your_own&nameid=0ad' and the only thing we actually care about in the response is "id": 57.

There are similar things for the other query curl --request GET 'https://api.mod.io/v1/games/57/mods?api_key=acf8fc07e3a8e9228ef4d5704c1659a1' (not the actual code, but equivalent, and easier to test), where we currently only need "name", "nameid", "summary", and "modfile": {"version", "filename", "filehash", "filesize", "download"} for each entry. All the other data is not really needed and it would be nicer if we could specify that when doing the query.

Depending on the infrastructure used this might also remove some ultimately unneccessary work the server has to do.

Request to rename endpoint from "Get All Mod Activity By Game" to "Get All Mod Activity". (https://docs.mod.io/#get-all-mod-activity-by-game)
Reasoning: Matches rest of documentation such as "Get All Mods" (which are implicitly "By Game") (https://docs.mod.io/#get-all-mods)

Currently all the #includes for the source code are in the header files, which avoids repetition, but pollutes any users of the SDK with unnecessary dependencies and system headers, since there's no way to access the library API without the headers. Clean headers make it easier to integrate with third-party code and avoid unnecessary conflicts.

• Given how C++ works, it's better to keep includes as close to the source as possible and avoid them in the header files, even if it causes repetition, since library headers can be included anywhere and pull everything along with them.
• The source files (.cpp) should carry most of the includes, as they're the ones calling functions. Header files (.h) only need to include other headers for types and defines they reference.
• The include/ folder should only contain header files with the library's public API (functions and classes exported by the DLL), all the others should stay in the src/ folder. The ModioC.h is a good example, as it defines nothing but the public API.

Tools like https://include-what-you-use.org/ can help automate this process.

The live API returns an online field on the member object but it's not listed on the documentation

API example containing the online field:
https://api.mod.io/v1/games/7/mods?api_key=aea55da460bd50aa338f2b3da7e81f1f&_limit=1

Missing online field on the documentation:
https://docs.mod.io/#member-object

(Since in parts this API is trying to provide similar things as some package managers, learning some lessons from those is a good thing to do.)

It would be nice if one could optionally sign (most likely GPG (at least that is what most *nix package managers or related tools use, I'll still point towards OpenBSDs signify to indicate that there are alternatives)) mod files, so users of the API could verify that the files are actually the same as the mod creator provided. This removes some need to trust the actual API endpoint too much.

• The Meta Cursor object is missing from the Browse endpoints Response Examples (i.e. Browse Games, Browse Mods)
  Example:
  "meta":{"cursor":{"current":null,"prev":null,"next":31346,"count":11}}

• The Meta Cursor object it's not explained on the documentation, I think the Filtering section is a good place to do it

• The cursor and offset params are missing from the Filtering documentation

"

When creating a mod using the Add Mod endpoint. If the optional param nameid is sent with an already existing value in mod.io, the server returns:

{"error":{"code":500,"message":"We experienced a server error attempting to complete your request. The issue has been logged and will be investigated, please try again later."}}

I think would be better if it returns 422 Unprocessable Entity with a message that explains that the mod could not be created because the nameid should be unique.

Missing:

• Mod.logo, .url, and .media
• Member
  Incorrect:
• Mod.member and .modfile listed as integer (instead of data structure)
• Modfile.member listed as integer (instead of data structure)

Currently if there's an error in modioInit due to an invalid parameter (eg. invalid root path, no write permissions, etc) the SDK just fails silently since nothing is logged and any web requests will just respond normally.

• Check for errors in modioInit and return true/false appropriately (will need an explicit ::init for C++)
• If the logger failed, log errors to stderr instead.

If I query for mods without OAuth2, are the results only those with status "auth" (as it is listed as the default)?

It would be nice if one could ask for "auth" and "unauth" (so "auth+unauth" but not any of "ban", "archive", or "delete") without using OAuth2. I'd like to provide users access to mods that have been checked by developers (possibly by default, after notifying users that they will connect to the internet and whatnot), but I'd rather not list every mod there for security reasons.

(Our mods include scripts, which might be malicious, and I'd rather not expose users to such mods without a big warning telling them that they might be putting their machine at risk. So only listing mods checked by some of our developers would be the right thing to do. There aren't a whole lot of scripts in most mods we've seen so far, and if there are more than that they most likely have been written by someone on the team.)

Also how does the process of marking a mod as "authorized" work, the only 3 occurances of "authorized" in the documetation are twice in the status description, and once for a 401 response code.

A popup message requesting moderator verification of 1 mod is shown despite the only mod added to the game being currently authorised.
Possible cache problem?

URL: https://tanks.mod.io/
User: melodatron

Is something around 225x57. Text description suggests 100x40 which is a different shape ratio than the actual header logo.
Images uploaded @ 100x40 don't fill up header logo's space, leaving black boxes on both sides.

API example containing the stars fields:
https://api.mod.io/v1/games/7/mods?api_key=aea55da460bd50aa338f2b3da7e81f1f&_limit=1

The stars field is not present in the documentation
https://docs.mod.io/#rating-object

Also, "Rating" on the descriptions has inconsistent caps. I think they should be all lowercase. The same applies to the nested Rating object on the mod documentation:
https://docs.mod.io/#mod-object

Right link might be instead http://docs.mod.io

Location:
https://docs.mod.io/#mod-object

The file paths returned are ugly in that one has to do tons of API requests instead of just being able to increment e.g. a version number and calling it done. This does not mean that there cannot be an API key in the URL allowing rate-limiting based on API keys.

This could be somewhat important for downstream projects that are packaged for some *nix systems, which would like to also package some mods and ship them. Would help a little with reducing the bandwidth and allow fully offline installation of mods.

?name-not-lk=dungeon - Get all results where texture does not occur in the name column.

Location: https://docs.mod.io/#filtering

What does mod.member mean? .author, .creator, or .owner might be better

This seems limiting for mods that release multiple versions, as there either need to be new "mods" for each release, or only a single version of a mod available.

I guess having modfile be modfiles and an array would help with this. Or having another query where one can actually retrieve all files (or just the most recent one) for a mod, or a game.

(In my current WIP patch for 0 A.D. there need to be two queries before all the neccessary data is retrieved, because I don't hard-code the game id (to allow for different API endpoints, and to not force possible future users of the engine to use the same).

Currently the code does something roughly equivalent (to the following commands)

curl --request GET 'https://api.mod.io/v1/games?api_key=use_your_own&nameid=0ad'
# parse {"data":[{"id":57," ...
curl --request GET 'https://api.mod.io/v1/games/57/mods?api_key=use_your_own'

. It would be a lot nicer (and reduce the number of queries, even though the code will cache the game id after the first query (at least after some more integration work)) to be able to do a single request and get the result for the second query.

Also why does the first query even return an array of data if ids are unique, so there can only be 1 or 0 returned entries?

Some games have built-in ZIP loading so mods don't need to be extracted to disk. Skipping this step makes the installation process much faster as it becomes a simple "move" operation and also requires less hard disk space.

I think the subscribe to mod endpoint should return the mod object. So game devs and users can decide to download the modfile just after subscribed.

We internally use some JSON data to handle mods and their compatibility. Parts of it are also provided in the mod/modfile data returned currently, however a few custom fields (best encapsulated in some "custom" object) that can be set when uploading a mod (or at a later point using some tool) would help a lot.

Mainly we wouldn't allow the user to download mods that are not compatible with the current version of the game. We could also easily show that there is a compatible update of the mod available, or if that requires a newer version of the game indicate that.

I guess limiting the size of the custom data would be important, but given the current mods the biggest of these files is 314 bytes. And most of that is the description, which wouldn't be included in the data I'd like to see stored with the mod files. So I guess limiting the custom data to something like 512 bytes should be plenty.