{"id":17298503,"url":"https://github.com/kamranayub/igdb-dotnet","last_synced_at":"2025-04-14T11:12:39.277Z","repository":{"id":34903446,"uuid":"186929925","full_name":"kamranayub/igdb-dotnet","owner":"kamranayub","description":".NET Core SDK for IGDB V4 API","archived":false,"fork":false,"pushed_at":"2024-07-31T20:35:58.000Z","size":165,"stargazers_count":75,"open_issues_count":5,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T11:12:28.947Z","etag":null,"topics":["csharp","dotnet","dotnet-core","igdb","igdb-api"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kamranayub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["kamranayub"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-05-16T01:42:24.000Z","updated_at":"2025-04-10T18:06:43.000Z","dependencies_parsed_at":"2022-09-01T00:52:35.234Z","dependency_job_id":"efdc0469-2d0d-424f-a937-7bbeb52fcc49","html_url":"https://github.com/kamranayub/igdb-dotnet","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Figdb-dotnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Figdb-dotnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Figdb-dotnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamranayub%2Figdb-dotnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kamranayub","download_url":"https://codeload.github.com/kamranayub/igdb-dotnet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248868766,"owners_count":21174758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","dotnet","dotnet-core","igdb","igdb-api"],"created_at":"2024-10-15T11:19:16.292Z","updated_at":"2025-04-14T11:12:39.250Z","avatar_url":"https://github.com/kamranayub.png","language":"C#","funding_links":["https://github.com/sponsors/kamranayub"],"categories":[],"sub_categories":[],"readme":"# IGDB .NET SDK\n\n[![.NET](https://github.com/kamranayub/igdb-dotnet/actions/workflows/dotnet.yml/badge.svg)](https://github.com/kamranayub/igdb-dotnet/actions/workflows/dotnet.yml) [![Nuget](https://img.shields.io/nuget/v/IGDB.svg)](https://www.nuget.org/packages/IGDB/)\n\nA wrapper around the [IGDBv4 API](https://api-docs.igdb.com) using .NET Core (compatible with .NET Standard 2.0+). Note, IGDBv3 is now deprecated and no longer supported so previous versions of this library (1.x) are no longer supported.\n\n## Where is this being used?\n\nI built this library primarily for [Keep Track of My Games](https://keeptrackofmygames.com), an app to help organize and track your game collection. That means I use this library in production and I'm motivated to keep it up-to-date and fix issues.\n\n## Usage\n\n### Install\n\nvia [Nuget](https://www.nuget.org/packages/IGDB/)\n\n    # .NET Core\n    dotnet add package IGDB\n\n    # .NET Framework\n    Install-Package IGDB\n\n    # Paket\n    paket add IGDB\n\n### Quickstart\n\nUses [RestEase](https://github.com/canton7/RestEase) so you can easily call the API methods. Since IGDB uses APIcalypse query language, you will need to pass the query as a string. _TODO: Create a query builder._\n\nEndpoints can be passed using the constants in `IGDB.IGDBClient.Endpoints` or as a custom string.\n\nModels are domain objects found in `IGDB.Models` and correspond directly to the [Endpoints documentation](https://api-docs.igdb.com/#endpoints).\n\nSome fields can be [expanded](https://api-docs.igdb.com/#expander) which is handled via the `IdentityOrValue` and `IdentitiesOrValues` wrapper.\n\nThe IGDB API uses the Twitch Developer program to power its API so it requires an OAuth client app ID and secret, which you can find in your [Developer Portal](https://dev.twitch.tv/console/apps). Passing these to the `IGDBClient` constructor will handle the OAuth bearer token management for you (see _Custom Token Management_ below for details).\n\nSee below for an example:\n\n```c#\nusing IGDB;\nusing IGDB.Models;\n\nvar igdb = new IGDBClient(\n  // Found in Twitch Developer portal for your app\n  Environment.GetEnvironmentVariable(\"IGDB_CLIENT_ID\"),\n  Environment.GetEnvironmentVariable(\"IGDB_CLIENT_SECRET\")\n);\n\n// Simple fields\nvar games = await igdb.QueryAsync\u003cGame\u003e(IGDBClient.Endpoints.Games, query: \"fields id,name; where id = 4;\");\nvar game = games.First();\ngame.Id; // 4\ngame.Name; // Thief\n\n// Reference fields\nvar games = await igdb.QueryAsync\u003cGame\u003e(IGDBClient.Endpoints.Games, query: \"fields id,name,cover; where id = 4;\");\nvar game = games.First();\ngame.Cover.Id.HasValue; // true\ngame.Cover.Id.Value; // 65441\n\n// Expanded fields\nvar games = await igdb.QueryAsync\u003cGame\u003e(IGDBClient.Endpoints.Games, query: \"fields id,name,cover.*; where id = 4;\");\nvar game = games.First();\n\n// Id will not be populated but the full Cover object will be\ngame.Cover.Id.HasValue; // false\ngame.Cover.Value.Width; // 756\ngame.Cover.Value.Height;\n```\n\n### Handling Query Counts\n\nYou can use the `QueryWithResponse` API to return the raw `HttpResponseMessage` along with the deserialized response through `GetContent()`.\n\nThere is an extension method available that will retrieve the `X-Count` header returned by IGDB on query endpoints. This avoids having to issue two requests to get the total results for a query. You also have full access to any headers through the `ResponseMessage` property.\n\n**See IGDB.Tests/Games.cs#ShouldReturnResponseWithHeaders** for an example test that covers this feature. You can also read more about the `Response\u003cT\u003e` [support in RestEase](https://github.com/canton7/RestEase?tab=readme-ov-file#return-types).\n\nAlternatively, you can also use the `CountAsync()` API to just retrieve the count for a query.\n\n### Custom Token Management\n\nBy default this client will request a OAuth bearer token on your behalf that is valid for 60 days and will store it statically **in memory**. If an invalid token is used and a 401 response is received, it will automatically acquire a new token and retry the request. See `TokenManagement.cs` for the default implementation.\n\nTo customize this behavior, such as storing the bearer token in persistent storage like SQL or NoSQL, you will have to pass your own `ITokenStore` implementation.\n\n```c#\nusing IGDB;\n\nclass CustomTokenStore : ITokenStore {\n\n  Task\u003cTwitchAccessToken\u003e GetTokenAsync() {\n\n    // Get token from database, etc.\n    var token = // ...\n    return token;\n  }\n\n  Task\u003cTwitchAccessToken\u003e StoreTokenAsync(TwitchAccessToken token) {\n    // Store new token in database, etc.\n    return token;\n  }\n\n}\n\n// Create an IGDB API client, passing custom token store\nvar api = new IGDBClient(clientId, clientSecret, new CustomTokenStore());\n```\n\n- `GetTokenAsync` - Gets a token\n- `StoreTokenAsync` - Stores a new token\n\nWhen using dependency injection, the lifetime of the `ITokenStore` can be whatever you prefer -- a singleton is used by default.\n\n\u003e Note: If you build a token store, please open a PR and add a link here so others can use it!\n\n### Default Serialization Settings\n\nIGDB uses some _interesting_ patterns to serialize responses. When using field expansion (`foo.*`) it will expand that JSON property to be an array of objects instead of just an array of IDs. The default serializer settings of this client will handle all of this for you. It also handles serializing/deserializing `snake_case` naming and Unix timestamps.\n\nTo get a reference to the default serializer settings (for example, to serialize/deserialize yourself separately), you can access the static variable `IGDBClient.DefaultJsonSerializerSettings`.\n\n### Images\n\nUse the `IGDB.ImageHelper` to generate URLs for images. It exposes the raw template URL `IGDB_IMAGE_TEMPLATE` and mapping `ImageSizeMap` of `ImageSize` enum to `string` value:\n\n```c#\nvar games = await igdb.QueryAsync\u003cGame\u003e(IGDB.IGDBClient.Endpoints.Games, query: \"fields artworks.image_id; where id = 4;\");\nvar artworkImageId = games.First().Artworks.Values.First().ImageId;\n\n// Thumbnail\nvar thumb = IGDB.ImageHelper.GetImageUrl(imageId: artworkImageId, size: ImageSize.Thumb, retina: false);\nvar thumb2X = IGDB.ImageHelper.GetImageUrl(imageId: artworkImageId, size: ImageSize.Thumb, retina: true);\n\n// Covers\nvar coverSmall = IGDB.ImageHelper.GetImageUrl(imageId: artworkImageId, size: ImageSize.CoverSmall, retina: false);\n```\n\n## Versioning Policy\n\nThis project follows semantic versioning closely, so any API changes that may cause a compiler error results in a major version bump. Non-breaking enhancements or features result in a minor version bump. Bug fixes that don't add new features result in a patch version bump.\n\n## Contributing\n\n### Prerequisites\n\n- .NET 6+\n- Visual Studio Code or VS 2017+\n\n### Local Development\n\nAdd environment variables:\n\n    export IGDB_CLIENT_ID=[your OAuth app client ID]\n    export IGDB_CLIENT_SECRET=[your OAuth app client secret]\n\nThese are found in your [Twitch Developer Console](https://dev.twitch.tv/console/apps).\n\nYou don't need this to be defined globally but it does need to be in scope while running `dotnet test`.\n\n    dotnet build\n    dotnet test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamranayub%2Figdb-dotnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkamranayub%2Figdb-dotnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamranayub%2Figdb-dotnet/lists"}