It’s Here, the New IGDB API
After many months of hard work and sleepless nights we are finally ready to announce the full release of our new major version of the API, dubbed API 3000! Let’s take a look at what all that work was for.
So What’s Changed
Let’s just start by concluding that the API is insanely popular. To this date we have given out more than 10 000 keys and we are starting to see some really cool projects (and game companies) actively using it. Having this many users have also allowed us to gather valuable feedback regarding improvements.
The primary focus of API 3000 has been to give more power to our users by simplifying data querying and provide better control over what data to retrieve with more advanced filtering and searching capabilities.
All the changes we’ve made to the structure of the API as well as all the new features meant that our existing pricing model didn’t make sense anymore and therefore we are introducing a brand new pricing plan.
The Free Tier Even More Free & Updated Pricing
The idea with the API has always been to allow other game related projects to come to life, by focusing less on data gathering and more on product development. Holding true to this motto we have always been very generous with our pricing plans and what it is possible to do in each tier of the API, e.g. storing data locally, allowing commercial projects and even competitive projects etc.
Being a startup ourselves our pricing rationale has always been that if you don’t earn money on your project (e.g. by being open source or in a pre-monetization phase), we don’t want to earn money on you. Are you, on the other hand, earning money on your project that we are feeding with data, then we want a very small slice of those earnings so that we can continue to work with our dream project — IGDB.
As expected, this generosity has been abused to an extent that has had a negative impact on the overall performance of the API and for the rest of our users, e.g. by users who just went in and mass downloaded the entire database, not paying anything even though they were clearly representing financially viable companies or projects.
So to counteract this behaviour we are revising our tiers:
The first tier: Free
In our revised free tier we are merging our old free and hobby tiers, giving it a 10k request limit per month making sure that hobby developers and startup projects have all the data they need. In this tier you are offered community support through our dedicated Discord channel.
The second tier: Pro — 99 USD per month
This tier is directed more towards professional users who have need for more requests (50K per month), additional features such as webhooks and multi querying as well as more kinds of data. This tier is intended towards companies or projects generating revenue. In this tier you are offered email support.
The third tier: Partner Program — Free
This tier includes everything that the Pro tier includes for free and is intended for non-commercial or projects that intend to monetize. In order to apply for this tier you need to regard the following requirements:
- Your projects needs to be live.
- For consumer oriented projects you will be asked to implement IGDB Login. With IGDB login you allow our community to login into your service using their IGDB credentials.
- Data exchange: The data you exchange with us (e.g. game ratings or metadata), we are allowed to share with all of our API users. This way you improve our database and help smaller projects in a way that is mutually beneficial.
- Give us credit: By showing our logo, stating that “The data was freely provided by IGDB.com” you give us credit and allow other users to find the API.
The fourth tier: Enterprise
The enterprise tier is fully customizable where we give you access to any data, features and request limits that you require, while having access to dedicated support. This tier is intended for companies and monetized projects.
A New Way to Calculate Requests
In this version of the API each query you make to the API will count as one request. And for every field in that query that reference another endpoint will count as an additional request. By doing this we hope to prevent users from requesting more fields than they actually need at any given time. An added benefit is that this encourages all users to be mindful of how they build their queries which can improve the response times of queries which in turn leads to a better user experience for end users.
Changing the Billing Period
We are changing our billing from Postpaid (API cost is billed at the end of the month), to Prepaid (API cost are billed at the beginning of the month), as this caused confusion among some users when they got billed even though they cancelled their API subscription.
Data Structure/ Renamed Fields
We are aware that sometimes the field names in API 2000 weren’t the easiest to understand so in the interest of making it easier to know what data is available under an endpoint we’ve renamed a lot of fields that previously had names that were less than descriptive. But we did not stop there, we also wanted to make the data a bit more granular in some places, e.g. data that were fields in API 2000 are now their own endpoint which is referenced from other endpoints. Let’s take a look at an example of this:
To the left is the website field of API 2000 in the games endpoint, and to the right is the same field in API 3000. Note how in API 3000 each website has an id, this means that you will now be able to select which fields you want to include in your response to a higher degree than before. There is also a new field called ‘trusted’, this is specific for websites and it indicates that a website link is verified to be safe.
Better Error Messages
Another change we are making in order to make the API more user friendly is to improve our error messages and make them more descriptive. Let’s take a look at an example of a new error message. Here we’ve accidentally tried to filter on first_release_dates instead of the proper singularised spelling used for that field and that gives the following error message.
We hope that you agree that this preferable to some of the old error messages which could look something like this:
Exclude Fields
Another smaller feature we’ve added for convenience is the ability to select all fields except a selection of fields for those cases when you want most of the fields in an endpoint but not all of them. A simple example query would look like this:
RIP Scroll Api
Previously we’ve had two different ways of doing pagination in the API, but for simplicity we’ll stick with using offset since this is by far the most used of the two; The issue with the old scroll was that it was not intuitive in how it was intended to be used and most users avoided to use it.
Better Filtering Capabilities
One of the most exciting improvements in the new version of the API is all the new possibilities when it comes to filtering. API 3000 will make it possible to to use logical operators between filters, which could look something like this:
The response from this example query will be games that fulfil one or both of two sets or requirements:
- Games released for for both PC (6), and PS4 (48) and also has the genre simulator (13).
- Games released for for both Switch (130), and PS4 (48) and also has the genre Role-Playing (13).
Another thing that’s new in this example is how the ids are specified for the platforms, for example:
- [6,48] in the example above means platforms 6 AND 48.
- (6,48) would be platform 6 OR 48.
- {6} would be exclusives for platform 6.
- (6) would be games released for platform 6 but it also includes multiplatform games as long as one of the platforms is the one you specified.
Protocol Buffers
The next big addition to the new API is that we now support Google Protocol Buffers which makes it possible to receive responses as for example a java class or an equivalent for any other major programming language.
Introducing APICalypse: Probably the Best Querying Language in the World
In order to develop an API with the syntax and power that we wanted we needed to not only develop a whole new API from the ground up but also our very own custom querying language called APICalypse (pun absolutely intended). The goal with APICalypse has from the start been to create a querying language with a low learning curve that is quick to get started with at the same time as it supports advanced queries.
We are really happy and proud of what we have created and therefore we would like to share this with other developers by releasing it as open source in the near future. As a step towards this that the language has its own dedicated website outlining the language. Check it out at apicalypse.io.
New Documentation
All of these changes will of course also affect the documentation, therefore we will launch a brand new documentation page that will be updated automatically whenever any changes are made. You can read more detailed information about all endpoints, fields, filters and much more at api-docs.igdb.com.
Transitioning to API 3000
You can find your v3 API key at api.igdb.com. Once you have your key, head over to our migration page in the new documentation.
We will have a 6 month transition period ending the 30th of June 2019 where both versions of the API are available in order to give our users plenty of time to make any necessary changes to their projects.
The History of the IGDB API
So let’s conclude this by taking a step back to the earliest days of the IGDB API to see how it all started and how we ended up where we are now and what our intentions are for API 3000. The IGDB API started as a small project we did on the side, mostly for fun. But since then it has grown to be one of the products we are the most proud of.
The first version we released of the API was called API 1000, “because every product name sounds cooler with a higher number”. This was written in Ruby on Rails which was the primary language of IGDB back in those days. This was a very basic implementation with limited features and a much more complex structure of the data, more or less mirroring that of our internal database.
The API became more popular than we had ever thought it would be, and this inspired us to start working on a major version upgrade. Naturally we stuck with the naming convention and released API 2000. This version focused more heavily on user friendliness, with a more understandable data structure and much more powerful searching and filtering capabilities. This was also when we started working with the API ourselves for the first time in our own products, our apps. This helped us find a ton of improvements and new features to add to the API. The expander functionality is one such feature. This version was also when we came to our senses and started moving away from Ruby on Rails and started to explore other languages to use instead. One of the languages we explored and ended up using for API 2000 was RUST. Using RUST increased the performance of the API and provided lower response times since the code is very fast and more memory efficient. But like every other iterative project there were still bugs and limitations that we weren’t able to solve without making breaking changes, which leads us to API 3000 (Yeah we’re kinda stuck with that naming convention now).
With API 3000 we decided to pull out all the stops and are aiming at providing the most powerful gaming API ever made. To make this possible we built our own custom querying language from scratch called APICalypse.
API 3000 is written in Kotlin which is slowly but surely becoming our language of choice here at IGDB. While it is based on the Java Virtual Machine it is not burdened by over 20 years of backwards compatibility like Java is. This together with the possibility of using any Java library makes it a modern language with really nice syntax while still being very safe and reliable to work with.
We mentioned that API 2000 was the first version of the API that we used ourselves for any of our products, with API 3000 we are taking that to the next level as well and it will be what’s supplying the new redesigned IGDB.com with all the information you can see there. This will push us even more to make this the best API possible for our users since we’ll be able to find bugs and come up with new features when we are using it ourselves.
What’s Next?
We jokingly talked to our CEO about other cool things we could do and started talking about API 4000. His response to this was that we could start working on API 4000 when his daughters have moved out (the youngest is two years old today). So that’s not in the near future at least, which in all honesty is exactly what we want as well, The goal of API 3000 has been from the start to create an API that is intended to be used at a larger scale and to last for a long time.
Instead we will be shifting our attention towards gathering more data and taking steps to ensure that we maintain a high level of quality when it comes to the data that we offer through our API and website.
And on that note we hope that you are just as excited as we are for this new API. Happy coding!
