An API, or an Application Programming Interface, is pretty complicated but in the case of the Hypxiel API (and simplicity) is an online service procided by Hypixel that allows you to query the data they have on their servers. This can be a wide range of things from player stats, to hypixel skyblock items, to a player's achievement points. All of this is able to be looked up though different sections, or endpoints, of the api.
The different areas/sections of the api are split up into something called Endpoints. An endpoint is what you see in a url, for example google.com/search. The part after the url tells the API what kind of data you are asking for. If you want player data, you'll use the Player endpoints. If you want to check the online staus of a player, you use the Status endpoint. We'll talk about which endpoint you should query depending on what data you want to get later.
As with many API's, not everyone is able to request information from it at will. With the Hpyixel API, you will need to get an API Key in order to access most of the data. To do this, you need to log into the Developer Dashboard on Hypixel's website, and generate a Developer API Key. Make sure you read the Terms of Service, and other legal documents before you go goof up your account.
Once you've generated a key, you can copy it to your clipboard to paste into your app's code. Be sure to NEVER share this code with anyone! (Including pushing it to a code repo like GitHub)
You can also see your limitations for the API key. Developer keys are only allowed a certain amount of requests per 5 minutes (300 seconds). It is up to you to keep track of how many requests you've done, and to not go over that. If you do, most of the time you'll just get back a failed request. Later we'll talk about a few different way to ensure you're not going over the limit.
Personally, I use VSCode for all of my python projects. They have a free community version, or you can use VS Code. Either way, the setup is fairly simple once you've installed python. Just make a folder somewhere on your computer (I'll use "Documents/HypixelApi/" for this example. Once you've made the folder, right click it and select Services. From that dropdown, select New Terminal at Folder
This will open up a Terminal in the same location as your project folder.
We need to setup our project's dependencies and virtual environment. While you could technically skip this step, this makes it really easy to use this code on a different computer, or in the future when you find this project after a few years of not thinking about it. It is also good practice to setup a dedicated environment for each project.
When we talk about a virtual environment for python, we're referring to a a folder "used to contain a specific Python interpreter and software libraries and binaries which are needed to support a project (library or application)." (Python Docs) We do this to have all the extra pieces of code that our program needs to successfully run. In python, doing this is ridiculously simple. All you need is 3 commands:
$ python3 -m venv envOnce you've ran the command, let it sit until it finishes. This might take 10-60 seconds. Now, we need to activate our environment. On Mac, use this command:
$ source env/bin/activateThe next thing we need to do is install a library that will let us make HTTP requests. Make sure you're in the virtual environment before installing any libraries. We'll use requests, which is really easy to install:
$ python3 -m pip install requestsThis command will install the library for us, and let us use it in our project.
Now that we have everything setup, we can start out by opening our folder in VSCode (or whatever IDE you use). First, you need to create a file named main.py in the project folder. This can be named whatever you want, but by convention (best practice) it should be named main.py.
Next, we need to create our entry point into our program. This way, when you run your app, the python interpreter knows where to start executing the code. In python, we do this by writing the following:
if __name__ == "__main__":
print("Hello world!")
With this, we can start programming in our logic. First off, we need to import the library that will let us call the Hypixel API. To do this, we'll use the requests library.
import requests
if __name__ == "__main__":
print("Hello world!")
Now we can use the library to call the Hypixel API. To do this, we'll need to specify the URL we want to make a request to. For the sake of this example I'll use the Skyblock Items endpoint, as you do not need an API Key for it. The URL looks like this:
url = "https://api.hypixel.net/v2/resources/skyblock/items"
Note that as of November 13th, 2023, the Hypixel API is on v2. If you'd like to learn more, you can read the forum post here.
We need a few things to request data programmatically. First, we need a request object. This object is a variable that will store all the data associated with making an HTTP request, such as Headers (more on that later), as well as empty fields for the request to fill once we execute the request.
There are several requests we can make via HTTP, the main ones being GET, POST, PUSH, PATCH, and DELETE. The only method the Hypixel API is used for is a GET request. Self explanatory, as we're wanting to get information. Since we're wanting to get information, we'll use the get function in the requests library. You'll need to pass in a string (URL) of where you want to send a request to as the 1st argument of the get function:
r = requests.get(url)
This well execute the get request to the specified URL. There are a lot of fields we can view from the object r, however the main ones we're going to focus on are these 3:
Note that not everything here has parentheses (). This is because objects in python (classes) have two main types of data associated with them: attributes (or fields) and methods. An attribute (or field) is a variable that belongs to an object or class and can be accessed directly. A method is a function that is defined within a class and is called on an instance of that class. In simple terms, a field is a value you access, while a method is function call that DOES something.
In our case, the .json() method serializes (fancy word for reads into an object) the get request's response into an object we can read. This allows us to easily get information like you would with any dictionary in python. There are 2 ways of sifting through the data. You can use indexing, or you can use a get function. Each have their pros and cons, however for the sake of simplicity, we'll be using indexing for most of this tutorial. If you'd like to learn about the get method (which I suggest you use), you can learn more about that here: gist.github.com/itzilly/ae35b1d4
Once you've executed the GET request and have the response object r, you can start to sift through the data. The response data is usually in JSON format, which is easy to parse in Python. Here's an example of how to access specific data from the response:
To access most of the endpoints on the Hypixel API, you'll need to include your API key in the request headers. This allows the server to authenticate your requests and keep track of your usage. Here’s how you can add your API key to the headers:
Each response from the Hypixel API includes headers that provide useful information, such as your remaining request limit. You can access these headers to ensure you stay within the allowed limits:
If you exceed the allowed number of requests, the API will respond with an error. You can handle this by adding a delay before retrying, or by exiting the app gracefully:
There are several third-party libraries that can simplify your interactions with the Hypixel API. Libraries like mcfetch and mcuuid can help with tasks such as fetching player UUIDs. Here’s how you can integrate one of these libraries into your project: