Appendix A: JSON
Introduction to JSON in the Riot Games API
This Appendix has been adapted from a tutorial originally written by @Austin (Lord Imrhial). All I've done is some light editing for clarity, and pulled code from the original jsfiddes.
The goal of this tutorial is to give you a quick crash course on JSON. As long as you have done some basic programming and/or scripting you should be able to follow along! This is a tutorial for beginners, written by a beginner.
Before we Begin
While not required for this tutorial, there is a Postman Collection available containing the API requests that were made to gather the data for this tutorial. Get it here:
Note that to use these requests yourself, you will need to replace <api-key> in each request URL with your API key
When a request is used, the name of the Postman request will be noted as follows
Postman: <Name of Request>
Overview of JSON
The reason most of you are here is to build an awesome League of Legends application, but in order to do this you must first understand how the Riot API works and how you can make your program reach it; the rest will be up to your own ingenuity and utilization of the API to build a successful application!
JSON is basically a String that is commonly used for data sending, this is also what the Riot API will give you when your application asks for information. I.E. If I asked for information on the summoner name, Lord Imrhial, I would get this:
{
"profileIconId": 3217,
"name": "Lord Imrhial",
"summonerLevel": 40,
"accountId": 36197973,
"id": 22421317,
"revisionDate": 1516167415000
}Postman: Get Summoner Info
Decoding JSON
Check out this code:
function summonerLookup() {
var SUMMONER_NAME = "LordImrhial";
var API_KEY = "MY_API_KEY";
requestData({
success: function (json) {
summonerLevel = json.summonerLevel;
summonerID = json.id;
}
});
}Note that running the code will not work because of cross-origin restrictions with the Riot API. However, the code is sufficient enough to explain how to work with JSON, which is the purpose of this Appendix
Within success: the main concept I want you to understand is where I set summonerLevel = and summonerID =. This is where I actually decode the JSON and pull out the information that I want. This following code will grab the summoner’s level: json.summonerLevel
Summoner ID would be the same as well: json.id
Now let’s look at why this works for a second. Take a look again at the JSON string for the summoner:
{
"profileIconId": 3217,
"name": "Lord Imrhial",
"summonerLevel": 40,
"accountId": 36197973,
"id": 22421317,
"revisionDate": 1516167415000
}Postman: Get Summoner Info
Notice how it is structured. All the data is included in a “nest” or set of braces.
In this example, we have the attributes id, name, profileIconId, revisionDate, accountId, and summonerLevel. Attributes are accessed with a period (.). Thus when I call json.id it gives me the attribute id.
Note that these can be nested, for example:
{
"first": {
"wins": 1
},
"second": {
"id": 2
}
}Instead of the earlier example where the value of an attribute (e.g. name) is just a value (Lord Imrhial), this example has a second "nest" or set of braces as the value of the attribute. To access the "nested" attributes, you would just use another period (.). Thus if I wanted to get the value 2, I would use json.second.id. If I wanted to get the value 1, I would use json.first.wins
JSON Object
So what about this json that we keep seeing? Well, notice how in the code at the beginning of the "Decoding JSON" section, the success function has json in parentheses. Whatever is in those parentheses is the JSON Object. This is the ENTIRE set of data that the URL returns. As you build larger and more complex URLs, you will begin to see how long some of these JSON strings can get and why they are all stored using attributes.
More Practice!
Here is a practice problem.
function summonerLookup() {
var SUMMONER_NAME = "LordImrhial";
var API_KEY = "MY_API_KEY";
requestData({
success: function (json) {
summonerLevel = json.summonerLevel;
summonerID = json.id;
// give sumName the Summoner Name from the json Object
sumName = ??;
}
});
}Think about how to modify the code above to set sumName to the json’s value for Summoner Name.
Answer
function summonerLookup() { var SUMMONER_NAME = "LordImrhial"; var API_KEY = "MY_API_KEY"; requestData({ success: function (json) { summonerLevel = json.summonerLevel; summonerID = json.id; // give sumName the Summoner Name from the json Object sumName = json.name; } }); }
For an added challenge, try to get the other attributes. Practice makes perfect!
JSON Nested Data
The examples thus far have been pretty simple, so let’s look at nested data. As mentioned, each subset of braces represents an attribute, obviously all summoners only have one name, id, icon, etc.. So what about when you call APIs that have multiple items for attributes?
Take a look at this sample JSON (it is a simplified version of what the API returns for getting all challenger players. Use the postman request to see the full response):+
{
"tier": "CHALLENGER",
"queue": "RANKED_SOLO_5x5",
"leagueId": "930faadc-f191-3fc0-b715-79804ef73cfc",
"name": "Taric's Shadehunters",
"entries": [
{
"hotStreak": true,
"wins": 72,
"veteran": false,
"losses": 63,
"rank": "I",
"playerOrTeamName": "rovex",
"inactive": false,
"playerOrTeamId": "39957695",
"freshBlood": true,
"leaguePoints": 166
},
{
"hotStreak": true,
"wins": 86,
"veteran": false,
"losses": 60,
"rank": "I",
"playerOrTeamName": "ssalctuO",
"inactive": false,
"playerOrTeamId": "38960497",
"freshBlood": false,
"leaguePoints": 331
},
{
"hotStreak": false,
"wins": 101,
"veteran": true,
"losses": 81,
"rank": "I",
"playerOrTeamName": "Game1234",
"inactive": false,
"playerOrTeamId": "88490180",
"freshBlood": false,
"leaguePoints": 623
}
]
}Postman: Get Challenger Leagues
It looks similar in structure to what we had before, where there were multiple nests of data. However, this time we also have straight brackets [ ] in addition to curly braces { }.
JSON Arrays
At this point you might be confused. entries has a nest as well, but there are duplicate attributes like wins and losses … how do you tell them apart? Well this is why JSON is so cool, it basically is a string full of “arrays”. If you are not familiar with arrays, they are basically collections of data, each value with an “index”.
If I wanted to get the first wins and losses (72 wins and 63 losses), I would just say the following: json.entries[0].wins and json.entries[0].losses , I say [0], because 0 is the first index in an array.
In most programming languages, the first index of an array is 0, not 1
If I wanted the second wins and losses (86, 60), then I would say json.entries[1].winsand json.entries[1].losses, and so on for any other items.
Most of the API’s data will have arrays and these arrays are what will contain all of the cool stuff to build your application.
Let’s look some more sample code:
function letsGetChallengerPlayers() {
requestData({
success: function (resp) {
var numberOfPlayers = resp.entries.length;
var numberOfWinsForFirstPlayer = resp.entries[0].wins;
}
});
}As you can see this is similar to the summonerLookup() function, except it uses the challenger players JSON that we just looked at above.
Let’s walk through the function:
In this function I call
success(resp), what does this mean? Wellrespis the variable that now holds the JSON object, you can call this variable whatever you’d like, just know that it will always hold your JSON object.I then set the values of the output. I check the length of all the
entries(just for fun), using.length..lengthis Javascript, and it will return the size of an array. Notice the next line,resp.entries[0].wins, as you can probably guess, I grab the first entry, but then ask for its attribute,name.
Nested JSON Practice
Try to grab the following details from the JSON at the beginning of "JSON Nested Data" (using resp as the variable that holds the JSON object):
The
queueof the objectThe number of league points of the second entry in the
entriesarrayThe
playerOrTeamNameof the third entry
Answers:
resp.queue
resp.entries[1].leaguePoints
resp.entries[2].playerOrTeamNameRemember that the first object in an array is at index 0, so the second will be at index 1, and the third at index 2, and so forth
Pulling all JSON Array Data
If you are looking ahead, you might be thinking either A. manually calling all of this stuff is going to be rough, or B how do I keep this dynamic. As in, if I have a program that asks for the first 10 pages, but a user only has 9, how do I for see this so my program will not crash.
Well JavaScript has some nice functions to determine this ahead of time, like .length or foreach. Check out this example below where I utilize foreach to get all the wins for everyone in challenger.
function getEveryonesWinsInChallenger(resp) {
numberOfEntries = resp.entries.length;
resp.entries.forEach(function (entry) {
console.log("Number of wins: " + entry.wins);
});
}Looks similar to letsGetChallengerPlayers(), except I added a foreach at the bottom. Carefully exam it. What foreach does, is look at everything with the preceding criteria, so when I say resp.entries.forEach(function (entry)), the program will say, ”Okay, I will look at each entry IN entries IN resp, and refer to that element as entry."
Thus when I say entry.wins, this is actually saying resp.entries.wins. And since it is a foreach, it is really doing resp.entries[0-length].wins.
Pretty cool huh!
Conclusion
If you have been able to follow along then I think you are on a good foot to start exploring the other API’s. Learning JSON, is a trial and error thing, if you ever get stuck and become frustrated just head to the API Documentation, pull up the method you are using, and look at it carefully. Try visualizing the decode within your head and it will click, promise!
I hope you enjoyed this beginner tutorial, if you would like some more tutorials please join the API discord and let me know. I am not the best teacher, but I enjoy this stuff. :D
-- Lord Imrhial
Last updated