Modrinth.Net 3.1.0-alpha

Modrinth.Net

• C# Wrapper for the Modrinth API

Usage

• Install the NuGet package

using Modrinth;

// You must provide a user-agent, and optionally an authentication token if you wish to access authenticated API endpoints
var client = new ModrinthClient(userAgent: "My_Awesome_Project", token: "Your_Authentication_Token");

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

Console.WriteLine(project.Description);

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;
using Modrinth.Client;

// 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 client = new ModrinthClient(userAgent: userAgent, token: "Your_Authentication_Token");

Search

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

using Modrinth;
using Modrinth.Client;

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

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

foreach (var project in search.Projects)
{
    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.Version("1.19.3"));
facets.Add(Facet.Category("magic"));

// This will create a query that looks like this:
// (category:adventure OR version:1.19.3) AND category:magic

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

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, or if the response body is not valid JSON
• This approach will be revisited in future versions

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.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.StatusCode}");
}

List of endpoints and their support in this library

Project endpoints

Version endpoints

Version file endpoints

User endpoints

Team endpoints

Tag endpoints

Miscellaneous endpoints