# 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: {% embed url="" %} **Note that to use these requests yourself, you will need to replace \ 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: \ ## 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: ```javascript { "profileIconId": 3217, "name": "Lord Imrhial", "summonerLevel": 40, "accountId": 36197973, "id": 22421317, "revisionDate": 1516167415000 } ``` > Postman: Get Summoner Info ## Decoding JSON Check out this code: ```javascript 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: ```javascript { "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: ```javascript { "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. ```javascript 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 > > ```javascript > 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):+ ```javascript { "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].wins`and `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: ```javascript 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: 1. In this function I call `success(resp)`, what does this mean? Well `resp` is 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. 2. I then set the values of the output. I check the length of all the `entries` (just for fun), using `.length`. `.length` is 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): 1. The `queue` of the object 2. The number of league points of the second entry in the `entries` array 3. The `playerOrTeamName` of the third entry > Answers: > > 1. `resp.queue` > 2. `resp.entries[1].leaguePoints` > 3. `resp.entries[2].playerOrTeamName` > > Remember 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. ```javascript 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](https://developer.riotgames.com/api-methods/), 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://tutorials.wx-watch.com/appendix-a-json.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.