Modrinth.Net 3.6.0

Modrinth.Net

C# Wrapper for the Modrinth API

• For list of supported endpoints, see List of endpoints and their support in this library
  • The plan is to eventually cover all endpoints

Main attributes

• Automatic rate limiting
  • Retry count is configurable
• No dependencies
• Fully documented
• Support for .NET 8.0 and newer

Usage

• Install the NuGet package

using Modrinth;

var options = new ModrinthClientConfig 
{
    // Optional, if you want to access authenticated API endpoints
    ModrinthToken = "Your_Authentication_Token",
    // For Modrinth API, you must specify a user-agent
    // There is a default library user-agent, but it is recommended to specify your own
    UserAgent = "MyAwesomeProject"
};

var client = new ModrinthClient(options);

var project = await client.Project.GetAsync("sodium");

Console.WriteLine(project.Description);

But you don't have to provide options at all, you can just create a client with the default options:

var client = new ModrinthClient();

User-Agent

• You can also use the UserAgent class to help you create a valid user-agent
• User-Agent currently cannot be changed after the client has been created
• More info about the User-Agent can be found here

using Modrinth;

// Note: All properties are optional, and will be ignored if they are null or empty
var userAgent = new UserAgent
{
    ProjectName = "ProjectName",
    ProjectVersion = "1.0.0",
    GitHubUsername = "Username",
    Contact = "contact@contact.com"
};

var options = new ModrinthClientOptions
{
    UserAgent = userAgent.ToString()
};

var client = new ModrinthClient(options);

Search

• You can search for projects using the SearchAsync method, in the Project endpoint

using Modrinth;

var client = new ModrinthClient(userAgent: "My_Awesome_Project");

var search = await client.Project.SearchAsync("sodium");

foreach (var project in search.Hits)
{
    Console.WriteLine(project.Title);
}

Search with facets/filtering

• You can filter the search results by using facets, which are a way to filter the results by certain criteria
• You can read more about facets here
• You can create a FacetCollection and add facets to it, and then pass it to the SearchAsync method

Example:

// For search with facets, you first need to create a FacetCollection
var facets = new FacetCollection();

// Then you can add facets to it
// You add a facet by calling the Add method on the FacetCollection
// In one call, you can add multiple facets, they will be combined in an OR statement
// If you call Add again, the new facets will be combined in an AND statement with the previous ones

// Example:
facets.Add(Facet.Category("adventure"), Facet.Category("magic"));
facets.Add(Facet.Version("1.19.4"));

// This will create a query that looks like this:
// (category:adventure OR category:magic) AND version:1.19.4
// Basically it will search for projects that have the category "adventure" or "magic" on Minecraft version 1.19.4

// Then you can pass the FacetCollection to the SearchAsync method
var search = await _client.Project.SearchAsync("", facets: facets);

As FacetCollection implements ICollection<T>, you can use collection initializers to add facets to it, like this:

var facets = new FacetCollection
{
    { Facet.Category("adventure"), Facet.Category("magic") },
    { Facet.Version("1.19.4") }
};

Which will create the same query as the previous example.

Unsuccesful API calls

• If the API call was unsuccessful, the client will throw an ModrinthApiException exception
• This will be thrown if the API call return non-200 status code

using Modrinth;
using Modrinth.Exceptions;
using System.Net;

var client = new ModrinthClient(userAgent: "My_Awesome_Project");

try 
{
    var project = await _client.Project.GetAsync("non-existent-project");
    
    Console.WriteLine(project.Title);
}
// You can catch the exception and only handle the 404 status code
catch (ModrinthApiException e) when (e.Response.StatusCode == HttpStatusCode.NotFound) 
{
    Console.WriteLine("Project not found");
}
// Or you can catch the exception and handle all non-200 status codes
catch (ModrinthApiException e)
{
    Console.WriteLine($"API call failed with status code {e.Response.StatusCode}");
}

List of endpoints and their support in this library

Project endpoints

Version endpoints

Version file endpoints

User endpoints

Threads endpoints

🔐 All of the endpoints in this section require authentication.

Notifications endpoints

🔐 All of the endpoints in this section require authentication.

Team endpoints

Tag endpoints

Miscellaneous endpoints

Development

Testing

Library uses NUnit for testing.

To run tests, you can use the dotnet test command. To run authenticated tests, you need to set the ModrinthApiKey secret for the test project.

You can do this by running the following command in the terminal, in the root of the project:

dotnet user-secrets init --project .\test\Modrinth.Net.Test
dotnet user-secrets set ModrinthApiKey "Your_Authentication_Token" --project .\test\Modrinth.Net.Test

If you wish to remove the secret you can run:

dotnet user-secrets remove ModrinthApiKey --project .\test\Modrinth.Net.Test

Optionally, you can also set the MODRINTH_API_KEY environment variable, but secrets are preffered.

Disclaimer

This is not an official Modrinth project. This is a third-party project that is not affiliated with Modrinth in any way.