Slingswap

Extend your plugin accessability with a neat JSON-based Web API!

General Information

Slingswap serves as a provider for REST API implementation within Bukkit or Spigot plugins. It runs a local web server on a configurable port (25560 by default, can be changed in config.yml) and listens to all requests performed on that web server. Any response will be returned in a JSON-format, so it's easily integratable into any web application you need it in.

A plugin needs to register any kind of request to Slingswap using "Hooks". A hook is basically a class registered by Slingswap along with its URL and method. Once called, hooks get passed the request URL, form data, query data and even header data to achieve a very flexible usage of the API.

Commands & Permissions

Because this plugin serves as an API provider and web server, there are no such things as commands and permissions needed. Concider this as an additional library that other plugins can make use of.

Implementation

Using the Slingswap-API is pretty easy. At first, add the Slingswap.jar to your build path / dependencies like usual.
Then you need to create a Hook:

// Implement the SlingHook Interface  
 public   class  MyHook  implements  SlingHook  {  
    @Override 
     public   void  ProcessRequest  (  SlingRequest request, SlingResponse response  )   {  
         /* 
        ** YOUR REQUEST HANDLING HERE 
        */  
     }  
 }

The handling of SlingRequest and SlingResponse will be explained in just a moment, because the only thing left to do is to register this Hook to Slingswap. You can do this in the onEnable() method of your plugin for example:

@Override 
 public   void  onEnable  (   )   {  
    Slingswap.  RegisterHook   (   "my/hook"  ,  new  MyHook  (   )   )   ;  
 }

That's it! Now if you call http://your-server:your-port/my/hook , the ProcessRequest method of MyHook will be called filled with all request information.

SlingRequest usage

request.  Header   (   "User-Agent"   )   ;         // Retrieve a header value.  
                                     // This case: User Agent.  
                                     // NULL if unset  
  
request.  Query   (   "data"   )   ;                 // Retrieve Data from Query.  
                                     // This case, if the URL is  
                                     // "/my/api?data=12345", the  
                                     // method will return "12345"  
          
request.  Body   (   "username"   )   ;             // Returns body data from a  
                                     // possible x-www-form-urlencoded  
                                     // POST or similar body

SlingResponse usage

response.  Code   =   404   ;                       // Set the HTTP/1.1 Response Code  
                                         // to a specific value, this case  
                                         // 404 Not Found  
  
response.  Data  .  Add   (   "key"  ,  "Value"   )   ;         // Adds "key" : "value" to the final  
                                         // JSON response. You can use nearly  
                                         // any base type for this - Strings,  
                                         // Integers, Floats, Boolean, as well  
                                         // as Arrays of those.

Nesting JSON response

In case you want to return nested JSON objects, take a look at the Storager object. Basically. response.Data already is a predefined Storager object in which you can put other Storager objects.

Be careful though : Don't mess around with any kinds of circular structure due to possible overall-fuckups of your server! My current JSON-parser will try to print this circular structure and - of course - will never end. I plan to implement a safety mechanism for preventing this in the future.

Storager nest  =   new  Storager  (   )   ;  

nest.  Add   (   "name"  ,  "Parter Peker"   )   ;  
nest.  Add   (   "age"  ,  12   )   ;  
nest.  Add   (   "height"  ,  1.48   )   ;  
nest.  Add   (   "imposter"  ,  true   )   ;  

response.  Data  .  Add   (   "personal_details"  , nest  )   ;

And of course - you also can create and add Storager arrays.