Tutorial To The Paladins/Smite API

To watch the youtube video corresponding to this article, please click here.

Introduction

Multiplayer games often have to store tons of information about the game and their players, such as details about characters and weapon stats in the game, as well as the levels, experience, and money for each player, among many other things. Some of the companies that own these games are nice enough to provide access to their databases, so that fan websites and tools can be created by independent developers and players to further enhance the game and create useful resources.

---

Hi-Rez Studios, the company that make the games Smite and Paladins, offers such a service: The Smite/Paladins API. Any developer that requests credentials and gets approved gets access to some documentation about the API, a valid API key, and an invite to a secret chat group with other developers.

In this blog post, we'll look at what the API offers, we'll see how to use the API, and we'll take a look at some examples websites that are made using the API. 

---

What Does The API Do?

Basically, Hi-Rez has a database with a bunch of information for their in-game numbers, as well as player information. The API lets us access that information via certain endpoints. 

For example, one endpoint that we're given access to is the following:

/getmatchhistory[ResponseFormat]/{developerId}/{signature}/{session}/{timestamp}/{player}
Gets recent matches and high level match statistics for a particular player.

As the description states, if we supply a player's name to the endpoint, then Hi-Rez's servers will search their database for the match history of that player, format it, and send it back to us. 

And the API has endpoints for a bunch of other stuff, not just match history. Of course, it's up to us, as the developers to make the best use of the API and be as creative as possible. 

But what about all that other stuff? Response format? Signature? How do we actually use this "endpoint" to get a player's match history? Well...you have to write some code. 

---

Using The API (Low-Level Details)

The Paladins/Smite API works exactly as any other API does: it's a simple GET request to a special URL, that would even work in your browser if you entered it there. For a PC Paladins player, the URL for /getmatchhistory would look something like this:

http://api.paladins.com/paladinsapi.sv/getmatchhistory[ResponseFormat]/{developerId}/{signature}/{session}/{timestamp}/{player}

It's the same as before, but we added a base url in front the endpoint. So what's the deal with the other stuff?

ResponseFormat - JSON or XML. 
developerId - It was given to us when we got accepted. Every developer has one. 
Timestamp - The time the request was made.
​Player - The name of the player that we're stalking. 

"Signature" and "session" are a bit tricky...Hi-Rez certainly didn't make this noob friendly.

Signatures
A signature is when you add the following together:

developerId + method name ("getmatchhistory" in this case) + authenticationKey (given to us when we were accepted) + timestamp

And then you hash that with an MD5 algorithm. Sounds hard? Lol, yeah it is. 

Sessions
Sessions are created with a special endpoint called /createsession. Basically, you open a connection with Hi-Rez's servers for 15 minutes by getting a special authentication token to be able to use other endpoints. 

/createsession[ResponseFormat]/{developerId}/{signature}/{timestamp}
A required step to Authenticate the developerId/signature for further API use.

So at least once every 15 minutes, you have to call this endpoint to get a session id variable, which you then use to be able to access the other endpoints.

Using The API (High-Level Details) + Example Code 

"Okay, so we know how to use the API, but how to we actually use it??? Give an example!"

Using the API requires a programming language. You can use whatever language you want, but to be honest, NodeJS is the easiest. (WAYYYY easier than C# and Java.)

Conveniently, one of the other developers wrote a NodeJS Wrapper for using some of the endpoints, which you can see here. We're going to be using it. (I'm going to assume you have NodeJS installed. If not, check out the beginning of this blog post.)

On your computer in a folder you want to work in, initiate a node project, and create a file named "config.js" and a file named "index.js" with the following commands in your terminal:

npm init
touch config.js
touch index.js

Next, we'll install the Paladins wrapper library to our project.

npm install paladins-api --save

Open "config.js" and add the following code:

1 2 3 4 5 6 7

var config = { devId: "2211", authKey: "23DF3C7E9BD14D84BF892AD206B6755C" }; module.exports = config;

Of course, enter your own credentials with the devId and authKey that you were given.

Next, open "index.js" and add the following code:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

var fs = require('fs'); // Write to file. const paladins = require('paladins-api'); // API wrapper. var config = require('./config'); // Credentials. const pal = new paladins(config.devId, config.authKey); // Give our credentials. // Connect to Paladins API by creating a session. pal.connect('PC', (err, res) => { // Connection worked. if(!err) { var sessionId = res; // Call /GetMatchHistory using the wrapper. pal.getMatchHistory(sessionId, 'PC', 'z1unknown', (err, res) => { // It worked and we got a response, so... if(!err) { // Write the output to a file. const content = JSON.stringify(res); fs.writeFile("out.txt", content, 'utf8', function (err) { if (err) { return console.log(err); } console.log("Response saved! Done."); }); } }); } });

To be honest, this code is sort of bad and I wouldn't actually write my code like this, but it's just a simple example...

The code uses the wrapper to create a session, ​and then calls /GetMatchHistory on player "z1unknown". The results are saved to the file "out.txt". 

​To run the code:

node index.js

You can view the results in out.txt. Of course, the results are ugly and you should use a tool to format the JSON to look nicer.

Of course, this was just a demonstration of one endpoint that we didn't actually do anything with. It takes creativity to parse this information and make it useful. Let's look at a few examples of people who actually use the Paladins/Smite API to do nice things.

---

Websites That Use the API

A few examples of websites that make use of the Paladins API are as follows:

paladins.guru - Shows player match history and generates an ELO for them.
The Better Meta - Analyzes champion/player/win performance for each patch. 
hirez-gql-api.now.sh/graphql - Allows for simplified API calls right in the browser. Here's an example, getting some details for a certain Paladins match.
kusqt.com - Shows Paladin player loadouts.

---

Conclusion

In this post, we saw how to use the Paladins/Smite API, how it works, and we even demonstrated using it in our own code. If you want to use the API, then feel free to request access, and try to program something cool.

Shout out to the active developers who use the API, and HirezAaron, who is the lead developer for the API that everyone pokes when something goes wrong or when we need something. 

It's possible that I'll make a blog post for using the API to make a website, which would include the best practices and some architecture drawings, so keep an eye out. 

Here's the youtube video for this article, if you want to see a walkthrough/talkthrough of the coding/concepts.

​Like this content and want more? Feel free to look around and find another blog post that interests you. You can also contact me through one of the various social media channels. 

Twitter: @srcmake
Discord: srcmake#3644
Youtube: srcmake
Twitch: www.twitch.tv/srcmake
​Github: srcmake