Documentation.md

@@ -4,7 +4,7 @@
 
 
 ## Creating a server
-We shown how to create and start a web service on our [starting site](Home). Sparkling analyzes the methods of the given handler object and uses Spark to add both a GET and a POST request for each method, together with parameter and return value conversion. Further, it creates a documentation site for the handler object, listing all service methods available together with a generated Java Interface for Java client instance creation.
+We shown how to create and start a web service on our [starting site](Home). Sparkling analyzes the methods of the given handler object and uses Spark to add __both a GET and a POST__ endpoint for each method, together with parameter and return value conversion. Further, it creates a documentation site for the handler object, listing all service methods available together with a generated Java interface for Java client instance creation.
 
 You have some possibilities to control server creation with Sparkling:
 * __Pick the methods__ that should be available via the server:
@@ -20,9 +20,47 @@ You have some possibilities to control server creation with Sparkling:
 Since Sparkling simply connects the Spark server to the handler methods with [Spark](http://sparkjava.com/), you can use __all Spark functionality__ furthermore. Nothing special. Add new requests before or after you add a handler with Sparkling, deal with https, and plenty of more. Look into the fantastic [Spark documentation](http://sparkjava.com/documentation) for all possibilities.
 
 ### Data conversion
-Parameter and return values
+When you create the service http calls on your own, you have to deal with how Sparkling converts the parameter and return values. In general, primitive types will be offered inside the service API as-is (Strings, Numbers and Boolean). All other classes that are used as parameter or return values will be converted to and from JSON. 
+
+An example call would look like this:
+
+    GET http://localhost:8080/myservice/mymethod?parameter=great
+    
+The following capabilities exist:
+
+*  __Primitive types__ (numbers, strings and boolean) will be transported as-is (simple strings)
+
+
+        GET http://localhost:8080/my-service/mymethod?simpleNumber=23
+        GET http://localhost:8080/my-service/mymethod?simpleBoolean=true
+        GET http://localhost:8080/my-service/mymethod?simpleString=a%20string%20with%20spaces
+    
+*  __Complex types__ will be converted into JSON representation
+
+        GET http://localhost:8080/my-service/mymethod?complexParam={"number":23,"string":"hello"}
+    
+*  __Arrays of primitive and complex types__ are permitted
+   
+*  __null String values__ are represented with the zero byte (ASCII 0 / NUL). Specify it with Url encoding: '?parameterNull=%00'
+
+        GET http://localhost:8080/my-service/mymethod?parameterNull=%00
+        
+*  __POST or GET__ is possible to make the call
+
+*  __Big data transfers__ (e.g. file uploads and downloads) are supported by InputStream parameters and return types. 
+    * The HTTP return values are of type `application/octet-stream`
+    * The parameters must be specified as multipart message parts: `Content-Type: multipart/form-data; boundary=...` 
+       * Each parameter values is sent in a separate part: `Content-Disposition: form-data; name="...PARAMETER_NAME..." `
+       * InputStream parameters must use mime-type `application/octet-stream` 
+       * All other parameters go as `application/x-www-form-urlencoded; charset=UTF-8` 
+
+* All parameters can be specified either as HTTP parameters or multipart message parts. Mixing is not possible.
+
+* You __cannot omit parameters in a request__ - all are needed by the server to find the request associated method. Simply set empty string and list values (e.g. parameter1=&parameter2=[ ]&parameterN=...).
+
+* If you have values of classes with an inheritance and you specify an interface or an upper class inside the method declaration, the default JSON conversion will fail because there is no dedicated type information inside the generated JSON Strings. For this case, you can annotate the parameter with `@Polymorph`. Doing this, we use [JSON-IO](https://github.com/jdereg/json-io) as serializer, that as of our knowledge is the only JSON serializer that is able to deal with class hierarchies at (de)serialization time. The specific types of the serialized objects will be added to the JSON containers if necessary.
+
 
-simple vrs json, Polymorph
 
 ### Java method parameter names
 Sparkling needs to know the parameter names of the handler object methods in order to offer according named parameters for the http GET and POST calls. Since the Java compiler does not provide them per default, we have to take care that Sparkling can get these names at server creation time.