Go client for the Internet Game Database API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
img Replace gopherigdb with smaller image Dec 12, 2017
test_data
.travis.yml
LICENSE Add License Dec 12, 2017
README.md
character.go Fix spacing in documentation Dec 4, 2017
character_test.go Fix SetOffset's valid input range Dec 3, 2017
collection.go
collection_test.go
company.go
company_test.go
credit.go
credit_test.go
encoder.go
endpoints.go
endpoints_test.go
engine.go
engine_test.go
enums.go
enums_test.go
error.go Add additional status code checking Dec 6, 2017
error_test.go Add additional status code checking Dec 6, 2017
feed.go
feed_test.go
franchise.go
franchise_test.go Fix spelling Dec 7, 2017
game.go
game_test.go
gamemode.go
gamemode_test.go Fix spelling Dec 7, 2017
genre.go Fix spacing in documentation Dec 4, 2017
genre_test.go
igdb.go
igdb_test.go Export IntsToStrings Jan 4, 2018
image.go
image_test.go
keyword.go
keyword_test.go
options.go Refactor SetFilter to remove cyclomatic complexity Jan 2, 2018
options_test.go Refactor SetFilter to remove cyclomatic complexity Jan 2, 2018
page.go
page_test.go
person.go
person_test.go Fix spelling Dec 7, 2017
perspective.go
perspective_test.go
platform.go
platform_test.go
pulse.go Fix spacing in documentation Dec 4, 2017
pulse_test.go
pulsegroup.go
pulsegroup_test.go
pulsesource.go Fix spacing in documentation Dec 4, 2017
pulsesource_test.go
releasedate.go
releasedate_test.go Fix SetOffset's valid input range Dec 3, 2017
review.go Fix spacing in documentation Dec 4, 2017
review_test.go
tag.go
tag_test.go
testing.go
theme.go
theme_test.go
title.go
title_test.go
version.go
version_test.go

README.md

IGDB

GoDoc Build Status Coverage Status

Communicate with the Internet Game Database API quickly and easily with the igdb Go package. With the igdb client, you can retrieve extensive information on any number of video games, characters, companies, reviews, media, and much more. Every IGDB API endpoint is supported! You can go here for the full list of endpoints.

If you would like to help the Go igdb project, please submit a pull request - it's always greatly appreciated.

Installation

If you do not have Go installed yet, you can find installation instructions here. Please note that the package requires Go version 1.9 or later.

To pull the most recent version of igdb, use go get.

go get github.com/Henry-Sarabia/igdb

Then import the package into your project as you normally would.

import "github.com/Henry-Sarabia/igdb"

Now you're ready to Go.

Usage

Creating A Client

Before using the igdb package, you need to have an IGDB API key. If you do not have a key yet, you can sign up here.

Create a client with your API key to start communicating with the IGDB API.

client, err := igdb.NewClient("YOUR_API_KEY", nil)

If you need to use a preconfigured HTTP client, simply pass its address to the NewClient function.

client, err := igdb.NewClient("YOUR_API_KEY", &customClient)

Services

The client contains a distinct service for working with each of the IGDB API endpoints. Each service has a set of service functions that make specific API calls to their respective endpoint.

To start communicating with the IGDB, choose a service and call its service function. Take the Games service for example.

To search for a Game, use the Search service function.

games, err := client.Games.Search("zelda")

To retrieve several Games by their IGDB ID, use the List service function.

games, err := client.Games.List([]int{7346, 1721, 2777})

The rest of the service functions work much the same way; they are concise and behave as you would expect. The documentation contains several examples on how to use each service function.

Service functions by themselves allow you to retrieve a considerable amount of information from the IGDB but sometimes you need more control over the results being returned. For this reason, the igdb package provides a set of flexible functional options for customizing a service function's API call.

Functional Options

The igdb package uses what are called functional options to apply different query parameters to service function's API call. Functional options themselves are merely first order functions that are passed to a service function.

Let's walk through a few different functional option examples.

To set the limit of the amount of results returned from an API call, pass SetLimit to the service function.

revs, err := client.Reviews.Search("megaman", SetLimit(25))

As you can see, you simply need to pass the functional option as an argument to the service function.

To offset the results returned from an API call, pass SetOffset to the service function.

revs, err := client.Reviews.Search("megaman", SetOffset(10))

SetOffset is used to iterate through a large set of results that cannot be retrieved in a single API call. In this case, the first 10 results are ignored so we effectively iterated through to the next set of results by 10.

To set the order of the results returned from an API call, pass SetOrder much in the same way as the previous examples.

revs, err := client.Reviews.Search("megaman", SetOrder("views", igdb.OrderDescending))

SetOrder is used to specify in what order you want the results to be retrieved in and by what criteria. Here, SetOrder will retrieve the results with the most views first.

The remaining functional options are not unlike the examples we covered and are further described in the documentation.

Functional Option Composition

More often than not you will need to set more than one option for an API call. Fortunately, this functionality is supported through variadic functions and functional option composition.

First, service functions are variadic so you can pass in any number of functional options.

chars, err := client.Characters.Search(
    "mario",
    SetFields("id", "name", "games"),
    SetFilter("gender", "0"),
    SetLimit(5), 
    )

This API call will search the Characters endpoint using the query "mario", filter out any character that does not have a gender code of 0 (which in this case represents male), retrieve the id, name, and games fields, and return only up to 5 of these results.

Second, the igdb package provides a ComposeOptions function which takes any number of functional options as its parameters, composes them into a single functional option, and returns that composed functional option.

popularOpt := igdb.ComposeOptions(
    igdb.SetLimit(5),
    igdb.SetFields("name"),
	igdb.SetOrder("popularity", igdb.OrderDescending),
)

This call to ComposeOptions creates a single functional option that will allow you to retrieve the names of the top 5 most popular games if passed to the appropriate service function.

Functional option composition allows you to create custom functional options that can be reused in different API calls.

Taking the previous example, this can be done in the following way.

PS4, err := c.Games.List(
		nil,
		popularOpt,
		igdb.SetFilter("platforms", igdb.OpIn, "48"),    // filter out games not on PS4
    )
    
XBOX, err := c.Games.List(
		nil,
		popularOpt, 
		igdb.SetFilter("platforms", igdb.OpIn, "49"),    // filter out games not on XB1
    )

This example has two service function calls that each utilize the previously composed functional option in the same way but for different platforms. The first function retrieves the top 5 most popular PS4 games while the second function retrieves the top 5 most popular XB1 games.

Functional option composition reduces duplicate code and helps keep your code DRY. You can even compose newly composed functional options for even more finely grained control over similar API calls.

Examples

The repository contains several example mini-applications that demonstrate how one might use the igdb package.

If you have used the igdb package for a project and would like to have it featured here as a reference for new users, please submit an issue and I'll be sure to add it.

Contributions

If you would like to contribute to this project, please adhere to the following guidelines.

  • Submit an issue describing the problem.
  • Fork the repo and add your contribution.
  • Add appropriate tests.
  • Run go fmt, go vet, and golint.
  • Prefer idiomatic Go over non-idiomatic code.
  • Follow the basic Go conventions found here.
  • If in doubt, try to match your code to the current codebase.
  • Create a pull request with a description of your changes.

Again, contributions are greatly appreciated!

Special Thanks

  • You for your interest
  • John for the IGDB Gopher
  • Peter for the "Thank You" Gopher
  • Dave Cheney for his article on functional options
  • The DiscordGo and Go Spotify projects for inspiring me to create my own open source package for others to enjoy
  • The Awesome Go project for so many references to admire
  • The awesome people in the IGDB community who were always open to my questions