How do I create an API?

Hello! I have been searching for ages - How do I create a plugin which I can then use it's methods for another plugins... Are there any particular rules I have to follow when creating an API? How do I then set up my second plugin correctly so I can use these methods? There are not many tutorials at the moment which fit what I am looking for.

If you can help me out, I will be really grateful!
Thanks!

 

JTGaming2012
No there are no rules, but make sure to document what all your methods do and how to access them.

Usually, you would put an API accessor from your main class, so when people depend on your plugin, they can cast the result of PluginManager#getPlugin(String) to your main class, and call getAPI to store it.

getAPI should return a utility class with all static methods to do what you want your API to do. It should take objects from your API and parse them to do functionality provided by the API.

Events are even easier. You just make a class that eventually will have a superclass using org.bukkit.event.Event, and use PluginManager#callEvent(Event) to fire it. The user will be able to listen to it like a normal event.

 

Create methods/classses, than package them in a jar and reference that jar in your build path. Eclipse (and other IDEs I think) can reference other projects in your build path as well so you wouldn't need to package them in a jar.

 

I have never done anything like this before so I am afraid I am going to have to ask you to go in to detail! Here are a few questions I have...

• What does an API accessor look like? How can I create one? An example code would be nice!
• Is this what you mean by, "they can cast the result of PluginManager#getPlugin(<MyPluginName>) to your main class".

Code:java

this.getServer().getPluginManager().getPlugin(<MyPluginName>);

What do you mean by, "and call getAPI to store it."
What is the function? Where do I put it?

• So this, "getAPI should return a utility class with all static methods to do what you want your API to do"

Do I have to make a "myAPI" class in the API plugin and create some static methods of what I need doing. Do I have to link this class with the main API plugin class or not?

• In my plugin that uses the API, do I have to create and instance (I think that is what it is called)? How do I make that plugin able to access the other methods? How do I actually use other methods?

Here is what I have learnt so far:

Code:java

    //I put this before the onEnable method... I think it is called an instance...
    public final coins c = new coins();
 
    //This is how I use methods
    c.*some_method*(p.getName(), 10);

 

Whenever you create an object (new), you are creating an instance. Bukkit already does this for plugins when they load. For people to get an instance of your plugin, you'll need to make a static method returning your JavaPlugin.

 

Never do this. Static itself is in most cases wrong, but calling static methods on an instance is the worst you can do.

 

teej107 Could I have an example? As I said, I am very new to using external stuff...

 

JTGaming2012

 

teej107 Can I have a code example?

 

If that was the case, explain to me what the Bukkit class does then.

Static should be used for utility only final class, private constructor. There are correct ways to use static.

 

Indeed there are, but why the plugin manager for an instance of your plugin just to ask for a static class, why not just access said class directly? But this is a good way to obtain an instance for accessing instance methods.

 

mythbusterma
True, I forgot about that... Not sure how that escaped the back of my mind...

 

You could have a class called "Api" that has all the methods another plugin would need to interact with your plugin, such as setGold() getGold() etc. In your main class you could have a getApi() method that returns an instance of the Api class so other plugins can use it.

 

Well, if you need to ask perhaps you're not ready to make one yet...

 

mythbusterma How do I call this getApi() method? How do I lay it out; where do I put it in my main method?

 

JTGaming2012 This is a great question which most people don't truly understand. I'm going to try to explain it in a way you will understand. Making an API is only easy once you have an idea of what people want out of your plugin. Otherwise everything is hypothetical and hard to grasp.

First, some things to iterate over before I explain:
- Every Java project already has an "API": If you import your other java project into your current java project, then you can use ANY class in that whole. It's just hard to actually USEFUL way to use them.
- LIBs and APIs are basically the same for this level of understanding: Don't make things complicated until you have the basics down.

The Basics
What is an API?: An API is a set way for people to access certain classes and/or methods of a java project. In the end, it is really had to use a java project to it's fullest without an API though. You can think of this as a really cool computer. The java project is the computer itself, and the API are the ports on the computer (USB, Ethernet, HDMI, ect.). A computer can run without APIs (Mouse that plugs in USB, Internet that plugs into Ethernet) but it allows for other things to connect to it.
What is a LIB?: A LIB is the exact same thing as an API, except that it can't run on its own. Imagine this as a multitool. It has all these really cool features (mob handling, error log handling, ect.) but on it's own it can't do anything. A person has to use to his cool tools to build other things (other plugins).

How to make my own API?:

1. Find out what people will want to connect to in your java project
2. Document all the classes and methods people will use in your java project
3. Make a handler/manager/API for people to use

Now I'm guessing your can work through steps 1 and 2, but you're now stuck back at three. This is the hard part for everyone but it's very easy if you can understand what it means. Doing it is the easy part. All you're doing is allowing people to access methods, classes, events, and other useful things to implement or depend on in your plugin. It's kind of like an 'interface' and how other classes implement it.

Let's say you have a really cool plugin that allows players to ride pigs and have them go through a race track. It's really fun and everyone loves it. But people want more features faster than you can make them, and some of them are really specific so you can't do them. What do you do? YOU MAKE AN API! You create a class called CoolPluginAPI. Add a bunch of cool methods then you create a single static instance of this plugin and only allow one method to access. Or you make all the methods in the class static. Then you're done. BUT WOOOOAHHH. I didn't explain anything! Yes I did. I told you how to make it work. The part you may have overlooked is "add a bunch of cool methods". These methods are the API itself. Methods like:

Code:java

//Gets the PigVehcile instance for the player!
public PigVehcile getVehicle(Player p);
 
//Get current time for a player
public int getTime(Player p);
 
//Get the top time for a track
public int getTopTime(Track track);
 
//Get the instance for all the tracks
public List<Track> getTracks();
 
//Kick a player out of a game
public void kickPlayerFromGame(Player p);

Does this look familiar? Have you seen these things in other APIs? It's because you have. Now it might make since why you useing other peoples classes is now useful. There is no "PigVehicle" class in Bukkit, but since you have the project implemented, you can now use that class and all of it's methods. This is the very basics of an API.

But in the end an API can only be good as the code it is built on top of. If you have terrible code that has few methods and a bunch of code in each method, then you're API will be terrible. The more modular(flexible) your methods and overall plugin, then better you API will be. You can't have a shitty computer and expect people to want to plug their 4k monitors into it because in the end it won't do anything for their parts.

So what I'm saying is, you have a shitty computer. Please don't try to get other players to plug in their kind of shitty parts into your pile of crap to make it even worse. Wait until you got a decent computer and in the mean time, plugin to other really cool computers or maybe see how their built to better make your own. Your code is only worth something compared to someone else's code.

I'm really not trying to be mean to say you suck at coding. But every few months you code while you still learn to code (forever), you'll look back and be like. "Did I just fucking do that" or "Omg, I have a way better way of doing this!" so you go and fix it. You'll constantly be finding better and cooler ways and by the time you know it, you know more than the people in these forums. But you'll still be dwarfed on by make a programming guru. Not until you have reached a point where you realize you will never be the best programmer (because there isn't one), you can never learn everything (but just want to know the best directions to head), and you can read through advance code and understand what's going on will you be able to make a good API. But I guess you can always try

P.S. - I wrote this at 1:30 AM so don't judge me because I just made this all up on the spot
P.P.S - I'm not further explaining the fucking metaphors lol.