As this is regarding the wiki and about sections of SpongePowered, I thought this was the fitting category. Please move if not.
It has come to my attention that some people still can’t quite figure out what the difference between the API and an implementation is. These people are most commonly server owners and administrators who have zero interest or knowledge in development, and I think the issue is that they don’t know what it means when the words API and implementation are thrown around. Is there any way to maybe make this more clear to the not-development-savvy types? Or am I just finding all the right places to run into people who don’t read things?
Why not post what you see as the difference between API and implementation so that those people who want to know the differences can find it in this post?
Server owners shouldn’t have to care about the API, but I keep seeing people who can’t seem to understand that it is for plugin development and not running a server.
This is all in direct reference to some spammy posts in other parts of the forums where people are expecting to have a workable Sponge server within the next ~13 days of November because we are hoping to have a workable API in that time frame. Lack of understanding the difference between an API and an implemented API on top of a Minecraft server has lead impatient server owners to poke and prod like madness for download links for something that won’t be available for some time.
Personally, I think it’s important to be clear where possible so we can avoid misunderstandings like have been happening lately.
I think this has been discussed somewhat extensively before in various threads, and then people started getting really nit-picky with their definitions of API vs Implementation. Simply put (and hopefully not too obscurely), I’d compare the two to a vehicle. API is somewhat of the steering wheel (and dash panel controls and such), whereas the Implementation would be more or less the engine and functional parts of the vehicle. Server owners are drivers, developers are mechanics or vehicle modification junkies for the plugin devs.
Think the order would be that the implementation is the driver’s seat and controls; the engine, battery and essential stuff would be the api; and the plugins are the auxiliary stuff like AC, electric windows, lights, windshield cleaner and that stuff (the non-necesary componets to move the car).
The API would be the specification that you will have a wheel that is turned to change directions, what gears there will be and if it will be manual or automatic transmission, and that separeate foot pedals will be used to break and as the accelerator. It defines what the interface with the car will look like, how to properly interact with the provided interface, and what can be directed though the interface.
The implementation would be the actual, physical steering wheel, gear shift, seat, and pedals. The rest of the car a driver doesn’t directly interact with would be the underlying MC server.
Plugins would be the driver, he/she uses the implementation to interact with the vehicle.
An API is just a description/specification. An implementation is a functional thing that implements what is described by the API.
Edit:
To expland the analogy further: You need a vehicle to drive around in the same sense you need the implementation to run a server.
To train a driver would be like writing a plugin: you teach the driver the interface, that is the API. You only need to know as a driver how to interface with a car, you don’t actually need the physical car to know how to drive. With the knowledge of the interface you can drive multiple vehicles that share the same interface.
These bits-of-cars analogies aren’t very helpful. Surely it’d be more helpful for non-devs to say the API is the blueprint and the implementation is the actual car?
Guess this is what I meant when I said people got nit-picky about their definitions. We don’t need to explain in very high detail or it’ll be lost to the people we’d need to explain it to, whereas the others likely already understand.
I too don’t think a car is very well suited as an analogy… How about this:
There is a plain old wooden table. Literally, a sheet of plywood on top of some 2x2 beams, and treated with some stuff to make it not as rough as straight plywood. Now, when you bought this table, the manufacturer included a kit in which you can build a shelving unit that can be added into the table. The kit has a whole plethora of sizes, so you can make a one layer shelf a foot long, or four layer shelf the length of the table.
Thing is, you as a humble owner and user of a table have no idea how to build wooden shelves, and need someone else to do it. So you call your carpenter buddy and he takes your kit, and builds a shelf for you. The way he built it though is so that you can simply pop it into a hole in the table and have it be securely attached, but if at any time you want it out, you can simply pop it back out.
In this analogy, the table is the implementation - the equivalent of what CraftBukkit was, and what Sponge eventually will be. The shelf building kit was an API - an API on a technical level is beyond my understanding but as a plugin developer, all I know (and need to really) is that an API is what is used to build plugins. Then the final product of the shelf is a plugin. It sits nicely on the table, complimenting it, adding functionality, and because of how it was built, can be easily removed at the user’s demand.