What is a GET request?
Typically, when you want to get information from a server, your browser (the client) submits a request. The server the returns a response. The response returns information about the request the client made, as well as the content that client requested. The two main types of requests are GET and POST.
- GET requests are used to retrieve data
- POST requests are used to insert/update remote data
There is currently no way to submit POST requests via the BGG API, so we will only be using the API to retrieve data. Going forward, this tutorial will assume that you have knowledge of how to make a standard GET request.
Because your call's domain and your target's domain are different, your code will be attempting to make a cross-domain request, also known as a Cross-Origin Resource Sharing (CORS) request. This is different from an ordinary GET request. Unfortunately, BGG doesn't support CORS requests (and it has been asked to for quite a while) so your request will need some modification before it will work.
The current workaround for this issue is to mirror server-side access to the API using a reverse proxy and include all the necessary headers there. The reverse proxy we are going to examine is CORS Anywhere.
Installing CORS Anywhere
To begin using CORS-Anywhere, follow these instructions (for Windows computers):
- Download and install Node.js from here.
- Create a blank file and call it package.json.
- In the command prompt, navigate to the same directory and install CORS-Anywhere using Node Package Manager by typing npm install cors-anywhere. A folder titled node_modules should be auto-generated containing the CORS Anywhere installation.
- In \node_modules\cors-anywhere you should find a file called server.js. Run node on this file by typing node server.js in the command prompt. You should see something like the following if the server started correctly: Running CORS Anywhere on 127.0.0.1:8080. If you get an EACCES error, you may need to change the port by editing the port variable in the server.js file.
- Now you can create a new HTML document to test that CORS Anywhere is working. Insert the following code into the HTML file:
- If you open this file and check your browser's console, you should see a bunch of XML. If you do, that means CORS Anywhere is working and you're ready to move on to the next section. Don't worry about what all the XML means just yet, we'll get to that in a bit. Also, once CORS Anywhere is running, to stop it, you can just press Ctrl+C twice.
More about CORS Anywhere
You may notice that the request made in the previous code example looks a little strange. When using CORS Anywhere, you need to prefix all of your requests with a reference back to the server running CORS Anywhere. The address CORS Anywhere is running on is displayed when you first run the program, like so:
127.0.0.1 is my localhost, so I just prefixed my actual request with http://localhost:8080/. This means that my request will hit the CORS Anywhere server so that the correct headers will be added and my requested data can be delivered correctly.
Yes, you read correctly. There's no JSON here. BGG will only return XML data. XML is a little bit harder to read and work with than JSON, but it is not unmanageable. I would suggest getting Notepad++ and installing the XML Tools plugin which allows you to auto-format messy XML to make it easier to read.
Two API Versions
It is worth mentioning now that there are two different APIs in use by BGG: BGG XML API and BGG XML API2. They make calls in two different ways, but both are still usable. Here's a quick comparison of what a request for the XML data of the boardgame Catan would look like in each version:
BGG XML API
BGG XML API2
As mentioned in the introduction, BGG divides physical objects into "things". With API1, you need to say specifically what type of thing you are trying to access and provide the ID#, but with API2 you don't need the type - you only need the ID#, so it is a little easier to use. During this tutorial, we will be focusing only on BGG API2 as it is the more recently supported version.