Clearing Up API v. Implementation - Now With Advanced (kinda) Analogies!

[Kodfod]

While the above analogies are alright, I personally would like to use Legos for this. (Plus it get to use Legos!!!)

So lets start at the very basics. In the following figure, the green base would represent Forge, where Red would represent the Sponge API.

Now plugins hook into the Sponge API, what would that look like? Lets take a look:

The orange blocks would represent a very user-friendly plugin, or something like minigames. The yellow block would represent something that a Server-Owner would use heavily; think Essentials. The blue block would represent a smaller plugin.

Now lets look at what plugins that have dependencies look like.

In the above, The dark green pegs illustrate where a dependency exists. The gray blocks represent plugins that require the immediately connected block to exist for it to work. This means the top level grey blocks need 2 plugins: The middle layer of grey blocks, and the orange blocks. However, the Middle level of grey blocks only need the orange blocks to function. For this, Think of Multi-Verse & Multi-Verse Portals, both of which need a ‘core’ plugin (name eludes me currently).

Lets take a look at what would happen if we removed the middle grey layer because we think it’s not needed.

Now if this was the real world, the floating pieces would fall and break apart. Since the plugin still retains it’s dark green pegs, Sponge knows it’s needing something. So Sponge would read the instruction booklet provided by the grey blocks. Sponge finds that it needs another plugin that is not found, so it tosses aside these pieces and continues building the rest of the blocks.

Now let’s think of something DynMap. This would use Sponge, and other resources to preform it’s tasks. It would look something like this:

The two brown pieces represent the plugin and it’s connection to the lime green block, which represents the web server. The four black disks represent the User interface of the webpage. Please note that the white pieces are there to signal that is no longer Forge.

I hope this helps anyone, and if you find mistakes, please feel free to point them out so I may correct them.

Thanks!

[bdubz4552]

Well done, good creativity.

[OffLuffy]

I like the analogy, but not entirely sure if it’s particular to API vs Implementation. Seems more like Forge vs Sponge vs Plugins. I think most people understand the concept behind that, for the most part.

[williewillus]

Here’s another take on it:

An API could be seen as a “blueprint” of sorts, a contract that exposes what the Sponge methods are and what they will be able to do. Plugins developers can look at these abilities and code their plugins to utilize the API methods.

The implementation is the glue between the server and the API. The implementation takes the declarations the API sets out and makes them real. This allows the same API to have different implementations and bases, for example the primary implementation will be on top of MinecraftForge. The Sponge API, provides a getPosition() method for entities. While this method is the same name in the perspective of Sponge plugins, the internal implementation of how the position is retrieved differs from Forge to Glowstone and so on. Perhaps Forge grabs it from the entity while Glowstone queries the world list for the entity’s position (completely wrong but suits our analogy) but the API enforces that regardless of implementation, that method has to return a Vector3f with the correct position.

When the Sponge team is working on “designing the API” they are effectively designing what is visible to the developers of plugins. The actual “make it work” part is the implementation, which requires an actual working Forge 1.8 to test on.

[williewillus]

Here’s a stab at a car analogy:

The API is the design spec, what car makers (plugin devs) know they can utilize
I know I can turn the steering wheel left and right, I know I can up and downshift, brake, accelerate, whatever.
You don’t need the physical car (implementation) to be able to know these things.
Hence that is why the Sponge devs can create the API first without the implementation. They are defining how far the wheel can go, what the max speed is, etc. Plugin developers can already begin coding based on what the API says that they will be able to know once the actual car is made

The physical car is the implementation. Exactly how, physically, will the steering wheel limit be enforced, how physically the speed will be capped. Regardless of the car, any proper implementation is one that conforms to the limits and specifications set out by the design.

So Forge could be a super cool neon orange racecar and Glowstone could be an old buggy (not implying anything :p) , but as long as they enforce the same speed cap and wheel limits, etc. then they are a proper implementation of the design.

Right now our Forge 1.8 car isn’t even made yet so we can’t enforce the design specification on it.

[PierreC]

Overcomplicated. Here’s one:

Implementation uses API. Server owners use the implementation.

[OffLuffy]

Fair enough, although I guess some people may not understand what the implementation is. Hence the overly elaborate analogies trying to visualize the difference.

And I’m not entirely sure if I’m happy with “Implementation uses API”, I’d think of it more like “API is the blueprints/skeleton of the implementation”, as it simply defines/exposes what’s available in the implementation. Server’s run the implementation and developers use (mostly, avoiding NMS complications) the API.