SwiftApi

SwiftApi Logo

What is SwiftApi?

SwiftApi is an Apache Thrift based API for CraftBukkit Minecraft servers. This API allows simple calls to Bukkit methods over the internet using your favorite programming language. This plugin acts as the server component, allowing you to write client programs/websites/apps that can talk to your CraftBukkit server in almost any programming language!

What can you do with it?

Basically, SwiftApi allows you write awesome code and apps that can talk to and control your Minecraft server.

An example of such an app is MineCenter. Check it out at http://minecenter.org

Configuration Options

Edit the plugins/SwiftApi/config.yml file to your liking.

The most important options are:

# Authentication Information (CHANGE THESE)
username: admin
password: password
salt: saltines

Leaving these at default would make it easy for an attacker to use this API on your server.

Creating a Client App

Once you have downloaded the Apache Thrift compiler, you can create a client app in a few lines of code.

Check out the example PHP project here: https://github.com/phybros/swiftapi-example-php

Try the C#.NET/VB.NET tutorial here: http://dev.bukkit.org/server-mods/swiftapi/pages/examples/c-net-vb-net/

Generate the Client Library

You can generate the client library (example is in C#) by typing

thrift -r --gen csharp SwiftApi.thrift

The -r option tells the compiler to generate code for all files (including ones that are referenced in SwiftApi.thrift with the include directive. The gen csharp option tells the compiler to generate C# code. This command will leave you with a gen-csharp directory with all the code you need to connect to a server running the SwiftApi plugin.

Include the Code in your App

If you're using C#, you can just drag all the source files right into your client app to use them, or alternatively you could create a new project with the generated files to keep your code and the generated code seperate.

Examples

Visit the Examples page for examples of how to use the code.

Here's an example in C#:


//open a connection to a server running SwiftApi
TSocket socket = new TSocket("your.bukkitserver.org", 21111);
socket.Open();

//create a new SwiftApi client object
TBinaryProtocol protocol = new TBinaryProtocol(new TFramedTransport(socket));
SwiftApi.Client client = new SwiftApi.Client(protocol);

//get the server version and output it
Console.WriteLine("Server Version: " + client.getServerVersion(authString));

//close the connection
socket.Close();

Because the code is based on Apache thrift, you have access to many of the complex types in the CraftBukkit API, such as the Player object.

This example is in C#, but the thrift compiler is able to create libraries for almost ANY programming language.

Visit the Examples page for examples in some other languages

Available Programming Languages

As of version 0.9.0 of Apache Thrift, the following languages are available:

  • Actionscript 3 (AS3)
  • C (using GLib)
  • C
  • C#
  • Cocoa (Objective-C on Mac OS and iOS)
  • Delphi
  • Erlang
  • Go
  • Haskell
  • Java
  • Javascript
  • OCaml
  • Perl
  • PHP
  • Python (including Twisted async support)
  • Ruby
  • Smalltalk

Documentation

Full API documentation (generated by the Thrift compiler!) is available at http://willwarren.com/docs/swiftapi/latest.

Code

Think you can improve SwiftApi? Fork the repo on Bitbucket and submit a pull request!

Repo URL: https://bitbucket.org/phybros/swiftapi

Notes

This plugin sends anonymous usage statistics to http://mcstats.org/

To opt out, set opt-out to true in plugins/PluginMetrics/config.yml

You must login to post a comment. Don't have an account? Register to get one!

  • Avatar of tunabomber tunabomber Jul 22, 2014 at 20:15 UTC - 1 like

    Thanks phybros! I am so glad to get this 1.7 version. I haven't seen any issues with it yet. I should get some of the outstanding MineCenter items addressed soon now.

  • Avatar of phybros phybros Jul 20, 2014 at 01:10 UTC - 0 likes

    @Nensec: Go

    Thanks for the input - I agree with your angle

  • Avatar of deradic deradic Jul 19, 2014 at 12:23 UTC - 0 likes

    @Nensec: Go

    I think creating an extension api to easily create SwiftApi extensions like i proposed in this forum thread:http://dev.bukkit.org/bukkit-plugins/swiftapi/forum/68837-implementing-an-extension-api/?unread would be required in order not to bloat the core jar file.

    It would also allow other developers to create extensions with ease. Though i think it would still be preferable to first know the impact on memory/cpu of the thrift generated code. Because i will most defiantly create the extensions listed in that topic and add them to my server, so it has to be tuned for good performance.

  • Avatar of Nensec Nensec Jul 19, 2014 at 11:23 UTC - 1 like

    I've started to implement SwiftAPI in a project for my MC server, so far really loving the strong typed interface through this thrift ( never heard of it before! ) to communicate with my MC server!

    I suggest that if you intend to add things like Vault or Essentials you should keep the thrifty strong-typed interface, perhaps simply make them addons to the swift api instead of part of the core jar. If you (just) add one generic method for all plugins you gain compatibility with all mods, but you lose the strong-typed interface. So doing both might be an idea?

    After all these are server jars, not client. Keeping size down is nice, but not essential. Chopping it up into pieces you allow people to not have a bloated jar if they don't use essentials or vault, but for those who do you can just add them.

    Just my 2 euro cents.

  • Avatar of deradic deradic Jul 19, 2014 at 03:14 UTC - 0 likes

    -deleted

    Last edited Jul 19, 2014 by deradic
  • Avatar of deradic deradic Jul 18, 2014 at 21:55 UTC - 0 likes

    @phybros: Go

    Funny coincidence, i was just toying around with making bukkit plugins and extending swiftapi. I have created some minor working testing plugins but yet have to create a working swiftapi extension.

    I'm not a Java programmer, but i do feel i can contribute with some help/tips along the way. but most importantly i certainly want to and most probably will do anyways for personal requirements (web-cms for minecraft).

    I've created several forum threads instead not to fill up the comments here and allow better way of handling the issues/questions.

    If you could check those out i can start writing

    Last edited Jul 19, 2014 by deradic
  • Avatar of phybros phybros Jul 18, 2014 at 18:48 UTC - 0 likes

    @deradic: Go

    All good ideas. Do you know java? Want to help? :)

    One issue that I'm aware of is that the size of the SwiftApi jar is quite large. Partly due to shading the thrift library into it, and partly due to the fact that the thrift-generated code is very long and verbose.

    Basically, any time you add a new thrift method, it adds about 100k to the jar size (ish). The upcoming 0.9.2 release of thrift might address some of that, but we'll see.

    So anyway, if we add all the vault methods as well, it might get VERY large unless we can come up with a smart and generic way to pass method calls onto other plugins. Something along the lines of:

    callPluginMethod(String pluginName, String methodName, ...String parameters)
    

    So you'd call it like:

    callPluginMethod("vault", "methodName", "param1", "param2", "param3", "etc...");
    

    This way, SwiftApi only gets one extra method, but grants access to a whole world of other plugins.

    But I'm not familiar enough with the Vault or Essentials API to make an informed decision about that.

    Thoughts anyone?

  • Avatar of deradic deradic Jul 18, 2014 at 10:16 UTC - 0 likes

    Seems Essentials is also providing an API with awesome functionality to have remote.

  • Avatar of deradic deradic Jul 18, 2014 at 10:06 UTC - 0 likes

    <<reply 2272604="">>

    And if im not mistaken, you can also git clone the entire vaultapi and integrate it directly into your project, which will remove the need to install it seperately etc etc

    I'd say implementing this would without doubt make this the de-facto remote managing plugin for bukkit servers (if not already! lol :D)

  • Avatar of deradic deradic Jul 18, 2014 at 10:01 UTC - 0 likes

    Because the API implements sending server commands and getting the output, practicly everything is already possible with some regex matching of output. However, there's some thing that would greatly improve the overall plugin and should be relatively easy to implement (as far as i understood by checking up on some code)

    Vault is the second most installed plugin on Bukkit servers. As far as i can see, Vault provides an excelent API to manage some specific tasks that would be interesting to see in the SwiftAPI. If im correct, the VaultAPI interfaces with many other addons as can be seen here.

    Integrating all the VaultAPI commands and making Vault optional will introduce a very big range of extra services that would be interesting for web-services i am developing (think web-shop that will set permissions, vault items, item sets, etc) while still giving access to the core SwiftApi services if Vault is not installed.

    VaultAPI provides chat, economy, item/iteminfo and permissions functionality. If you look at the VaultAPI javadocs you can see all the nice goodies it provides. Having this implemented would be SOO awesome. And because the VaultAPI handles most of the internal stuff, i think it sould be fairly easy to implement.

    In any case, i hope that this is all correct and you feel this functionality belongs in the API. It would greatly increase the SwiftAPI use cases for my project, and im sure for many others aswell.

Facts

Date created
Sep 03, 2012
Categories
Last update
Jul 11, 2014
Development stage
Release
Language
  • enUS
License
GNU General Public License version 3 (GPLv3)
Curse link
SwiftApi
Downloads
5,299
Recent files

Authors