How to use the ‘Magic: The Gathering’ API’s ruby SDK
I have been playing ‘Magic: The Gathering’ for nearly fifteen years. Since the beginning of my program at the Flatiron School, I had been hoping that I would have the chance to create a MtG-related project. I found a few different MtG APIs, but after some research decided to go ‘with magicthegathering.io’, because they have a variety of SDKs for different languages, including Ruby.
In order to install the SDK, simply add gem ‘mtg_sdk’ to your gemfile.
I have only used external APIs a couple of times so far, so I figured that having this wrapper would make up for my lack of experience. I was wrong.
Several hours of trying to get the exact data I wanted taught me a lot about the structure of this API, my hope is that this article will help others avoid some of the more painful struggles that I had to go through.
Most querys to the MtG.io API are to the endpoints /sets or /cards. For those who do not know, Magic expansions are called sets, and typically feature between 250–350 cards. There are currently over 20,000 unique magic cards, some of which have been printed dozens of times with a variety of artwork across the games 27 year history. Between all of these different printings, complications caused by double-faced cards and the hundreds of versions of each basic land, there is a lot to unpack here. In fact, each card is about 100 lines when viewed as parsed JSON. The amount of data per card along with the sheer volume of data makes searching for an individual card by id a bit of a nightmare, as the id numbers go at least as high as 50,000, and are not in an order that most magic players would find intuitive.
Another thing to consider when choosing the data you want to pull from the API is that the responses are paginated, with a maximum of 100 cards per page. So, I decided to pull the first page of 100 cards, thinking that it would be 100 cards from Alpha, the first magic set ever. Instead, I got the first 100 cards from Tenth edition(a set released about 13 years after Alpha). At this point, I knew that I needed to rethink my approach. After referring to the API docs, I decided to take a look at the endpoint ‘/sets’. Unfortunately, this did not yield great results either. It was just a list of the sets and didn’t seem to have any data about the cards in that set.
It was hours later that I realized I needed to be querying for both card and set. In my earlier experimentation, I figured out that you could specify which page of cards you wanted and what you wanted the page size to be, as long as it was less than or equal to 100. So, it turns out that I was correct to query ‘/cards’, but I needed to pass in additional parameters.
Every set has a three letter code that it is referred to by. In the case of Zendikar Rising, the most recent set, the code is ‘znr’. In order to find the code, I looked at the ‘/sets’ endpoint in browser, and searched for the sets full name using command+F. You can do this for any set and quickly find the set code that you need.
Once I had the endpoints, it was time to decide what card data I wanted to actually include. I did not feel like everything was necessary, and in all honesty, the thought of using all of this data seemed overwhelming. So, I settled on what I thought would be the most important, built my card model, and got to seeding my database.
After running ‘rails db:seed’, I had my first 100 cards! Following the steps outlined in this article, you should be able to find the cards that you want much more easily.
