Introduction to APIs

API stands for Application Programming Interface. An API helps control how various software components are used. As mentioned in the previous chapter, Spigot includes the Minecraft code in a form that is easy for developers to utilize when creating plugins. Spigot has a lot of code that we need not access in order to create plugins. It also includes code that we should not tamper with, as it may cause the server to become unstable. Bukkit provides us with the interfaces that we can use to properly modify the game while restricting access to other portions of the code. An interface is essentially a shell of a class. It includes methods, but the methods are empty. The Spigot server contains classes for each interface. The classes implement the interfaces and fill each method with the appropriate code.

To explain this better, let's imagine the Bukkit API as a menu to a pizza shop. The menu contains different types of pizza, such as pepperoni, Hawaiian, and meat lovers. These menu items represent the interfaces within the API, with each interface having a method named makePizza. At this point, these pizzas cannot be eaten, because they are merely a concept. They are just items on a menu. But let's say that a pizza shop named All You Need is Pizza decides to open up and they use this menu, or API. This pizza shop can represent CraftBukkit. The pizza shop creates recipes for each item on the menu. This is equivalent to writing code for each makePizza method within the three interfaces. Thus, these recipes are the classes that implement the interfaces. However, these classes are still just a concept. It is not until the makePizza method is called that you have an instance of that class. This instance, or object, will be the tangible pizza that you can actually eat. Now, imagine that there is another pizza shop named Crazy Little Thing Called Pizza, which opens across the street from All You Need is Pizza. This new pizza shop will represent Spigot. Crazy Little Thing Called Pizza uses the exact same menu, or API, as All You Need is Pizza. However, its recipes, or implementations of the methods, may be different.

Using this same analogy, we can see the benefit of the API. As a customer, I can take a look at the menu and assemble an order. For example, I want to order a pepperoni pizza and a meat lovers pizza. Since I created my order based on the menu and both pizza shops implemented the same menu, either restaurant is able to fulfill my order. Likewise, a developer creates a plugin based on the Bukkit API. Both CraftBukkit and Spigot utilize the Bukkit API. Therefore, they will both support the plugin. The following diagram explains this relation between pizza and code:

Basically, Bukkit acts as a bridge between a plugin and the Spigot server. The Spigot team adds new classes, methods, and so on to the API as new features develop in Minecraft, but the preexisting code rarely changes. This ensures that Bukkit plugins will still function correctly months, or even years, from now even though new versions of Minecraft/Spigot are released. For example, if Minecraft were to change how an entity's health is handled, we would not see any difference.

The Spigot jar will account for this change by filling the getHeath method with the updated code. Then, when the plugin calls the getHealth method, it will function exactly as it had before the update. The addition of new Minecraft features, such as new items, is another example of how great the Bukkit API is. Let's say that we've created a plugin that gives food an expiration date. To check whether an item is food, we'll use the isEdible method. Minecraft continues to create new items. If one of these new items is Pumpkin Bread, Spigot will flag that type of item as edible and will therefore be given an expiration date by our plugin. A year from now, new food items will still be given expiration dates without us needing to change any of our code.