modrinth_api

Description:

modrinth api

Modrinth API for Dart #
Unofficial package for interacting with the Modrinth API, written in pure Dart!
This package currently targets Labrinth version 2.7.0 / 3b22f59.

Features #



Feature
Support




Search facets
✅


Alternative Modrinth instance
✅


Get a version by a file hash
✅


Get statistics about the Modrinth instance
✅


Automatic rate limiting
✅


Any requests that make changes to the database
❌🕒: planned for v1.0.0




🌐 Note: this library assumes an internet connection is available. If there is no connection available, the underlying http library will throw.


Early access #
As this package is still in a v0 phase, breaking changes could happen at any time.
For example, currently, most of the functions throw when something is not found. For most of these functions, that makes sense, but for some, where you don't have a clear "path" to take (clear path: e.g. search --> project id --> getProject() --> version ids --> getVersion()), it also throws, instead of returning a null value. I would like to change that, but the foundation of the functions has been laid, and so using them should work with just a bit of finicking around.

Getting started #
Install the library into your project like so, in your terminal:
dart pub add modrinth_api
copied to clipboard
Before using the API, import and then initialize the API:
import "package:modrinth_api/modrinth_api.dart";

void main() async {
final api = ModrinthApi(project: "my_test_project");
}
copied to clipboard

Note that you have to put in a name for your project (even better: insert your (GitHub) username as well). This makes it easier for the developers of the API to see who is using this package, might something go wrong with rate limiting or the content which is uploaded.

If you have an API key, you can specify it as such:
final api = ModrinthApi(
project: "my_test_project",
apiKey: "my_api_key",
);
copied to clipboard
Adding an API key allows you to access functions such as getAuthenticatedUser, getUserNotifications, getUserFollowedProjects and getUserPayoutHistory.
Might you want to use the staging API server - which is perfect for debugging & testing purposes - or just use another Modrinth instance, you can specify a custom baseUrl in the constructor like so:
final api = ModrinthApi(
project: "my_test_project",
baseUrl: "https://staging-api.modrinth.com/v2",
);
copied to clipboard
Be sure to also dispose of your ModrinthApi instance once you're done using it, to prevent hangs even though your code is done running.
api.dispose();
copied to clipboard

Usage #
Searching for projects #
Searching can be done with facets. How they work exactly is explained in the Labrinth docs.
Example for searching for only mods:
api.search(
facets: FacetListBuilder()
..and(
Facet(FacetType.project_type, "mod"),
),
);
copied to clipboard
As such, you can also use or() to add multiple facets to filter for any of the provided facets.
Example for searching for any project that is definitely a mod (and()) and could be targeting version 1.19 or 1.19.1 (or()), and limit the amount of results to 5.
final quiteExact = await api.search(
facets: FacetListBuilder()
..and(
Facet(FacetType.project_type, "mod"),
)
..or(
[
Facet(FacetType.versions, "1.19"),
Facet(FacetType.versions, "1.19.1"),
],
),
limit: 5,
);
copied to clipboard

Get a project by its id or slug #
final exactProject = await api.getProject("P7dR8mSH");
// ...Or:
final exactProject = await api.getProject("fabric-api");
copied to clipboard

Get a version by its id #
final exactVersion = await api.getVersion("nOI7bsDO");
copied to clipboard

Note: you cannot use slugs here, as versions don't have slugs.


Get a version by a file hash #
Note that calculating a file hash requires a library, such as crypto, as used in the following example:
import "dart:io";
import "package:crypto/crypto.dart";
import "package:modrinth_api/modrinth_api.dart";

void main() async {
final api = ModrinthApi(project: "my_test_project");

final File f = File("my_mod_jar.jar");

final List<int> input = await f.readAsBytes();

final String sha = sha1.convert(input).toString();

final Version foundVersion = await api.getVersionFromHash(sha);
}
copied to clipboard

...and many more functions! #
There's many functions in this library, and they are pretty straight-forward to use, in my opinion. Might you need some additional documentation or come across a bug, feel free to open an issue on the repository!

Credits #
Huge credits to the Labrinth team for writing their API docs! Without the docs, this package would be near-impossible to make.

License #
This library is licensed under the Apache License 2.0