Add architecture.md and sync_api.md

[immibis]

My thoughts on multiple repositories. Debate here

[stairman06]

Very well thought out proposal. The only thing I would change is the namespace prefix system to make it easier to tell what is a repo and what is a mod (something like repo_b:repo_c/mod_name would work fine).

Multiple repositories is definitely good for the community. If we want to make it as easy as possible for people to mirror repositories and for launcher developers to implement repositories, we will probably need to define a file hierarchy or some other method of storing metadata.

[immibis]

To be clear, the prefix is only for "foreign" projects. Someone uploads their project to Diluv, and Diluv just calls it project_name. Then Modrinth syncs from Diluv at some point, and the project appears in Modrinth's index as well, under the identifier diluv:project_name.

If there was always a prefix then perhaps it would make sense to have a special delimiter, but there isn't one.

Also the prefixes won't be enforced on the protocol level, only by convention. If someone wants to import ic2 from Modrinth onto their server and call it ic3@tardis?year=2025#fooled_you... (assuming those are all valid characters) then I don't think people will want to use such a low quality index.

[immibis]

Updated. Here is the start of an API for keeping projects synced between servers

[stairman06]

Looks great, I really like the idea of a standardized sync API. I only have one nitpick: I think the API version should be under a separate path (e.g. https://example.com/api/v1/project_list), but that's extremely minor and a matter of personal opinion.

[immibis]

I thought about that, but then if you update one URL - project_list_v2 but there's no project_v2 yet - you either duplicate the project route for v2 to keep the version number consistent, or you use both API versions at once. It's the project_list version, not the overall API version.

[immibis]

Example index: http://immibis.com/mcip_api_demo/project_list_v1 and project files: http://immibis.com/mcip_api_demo/project_v1/ID_HERE (format not specified yet, this is just an example)

Note: the Content-Type is wrong so your browser will want to download the files. curl may be more convenient Also it's just a static file host; it doesn't implement ?last_updated, which is okay because this is designed to be optional. Large index sites that host thousands of mods can implement ?last_updated to save bandwidth.

[stairman06]

Good example. I think what you've proposed with the demo and the sync API documentation works well. All we need now for the sync API to be completed is to finish the manifest format.

[immibis]

More stuff! I'm still not sure how categories should be done.

[immibis]

It doesn't make a lot of sense to have last_updated within the version list. That's a leftover. I suppose clients can assume the current value is the one in the index, but if there's a change after the client fetches the index and before it fetches the project info, it might save the wrong value.

[stairman06]

equivalent_versions is a very good solution to the multiple modloaders problem. I also like rel for files and for links. screenshots and authors seem good to me too. Eventually we'll need to decide what case style to use for the format and API (camelCase or snake_case). Personally I'm more of a fan of camelCase, but snake_case is fine too.

In terms of the API endpoints, description_v1 could be changed to something like info_v1 as it contains more than just the project description. Another endpoint that could be added would be version changelog (e.g. https://example.com/api/project/example_project/version/1.0.1-fabric/changelog_v1), or the changelog could be added to the existing "Project version files" endpoint.

On categories, I think the best solution would be an array of category objects containing name, and optionally url and icon:

{
  "categories": [
    {
      "name": "Magic",
      "url": "https://example.com/browse/mods?filter=magic",
      "icon": "https://example.com/static/magic-category.png"
    }
  ]
}

I think this category system is simple enough to not be geared towards a specific platform, but allows compatibility with existing ones.

At the project level, we may also need a type field to indicate whether it's a mod, resourcepack, datapack or any other type that could be handled by the format.

[immibis]

The main problem that I see with categories is that they don't translate between servers in a useful way. If MCIP Central has a IC2 category, but Modrinth has an Industrialcraft category, how do you know they're the same category?

[stairman06]

That's a good point I didn't think of. There could maybe be a mod-specific category that is tied to a mod ID, which could solve your example with IC2 but it wouldn't solve other category problems.

[l-Luna]

categories are generally based on conventions. we can expect different repositories to have the same set of standard categories, and to name them according to a set of rules, but we can't make that cover all possible use cases, so we could just make a set of guidelines for what a category's name/id should be (mod categories are mod IDs, other categories are lowercase non-plural adjectives), and expect repos to use roughly the same set, or be predictable.

[stairman06]

Conventions are probably what will end up being the best solution. Mods categories could be named mod-modid (e.g. mod-industrialcraft2 if IC2's ID is industrialcraft2) and other conventions you mentioned (lowercase non-plural adjectives) will probably end up working the best.

[stairman06]

I referred to this in my Spec Draft as the "MCIP Standardized API", however this API is more designed for syncing between hosts - should there be a separate standard API that launchers can use to search for and download projects, or should everything be integrated into a single API like this one?

[immibis]

In my imagination, servers can do whatever they want, and each one has its own API for launchers. The server will download the entire index, and then do whatever it wants with the entire index, so there's no need to query specific parts if it

[stairman06]

The situation I was thinking of was one where a launcher receives information about a project, and it requires a dependency from a host it has never heard of. This is where I see the benefit of a standard API - launchers don't have to implement custom handling for every host, all they need to know is one standard API. The manifest could simply provide a base URL for the host.

Perhaps servers could have their own API for more specific actions like searching, but I think a standard API that can be used for metadata would be beneficial.

[immibis]

The situation I was thinking of was one where a launcher receives information about a project, and it requires a dependency from a host it has never heard of.

That's why you import the metadata onto your own host.

[stairman06]

Hmm, you are right. If a host is serving info about a mod, they might as well serve full information about its dependencies as well.

[immibis]

Repository abandoned. Moved to MODIP