add documentation for feature silkimen#77

Author: Sefa Ilkimen

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.11.0
+
+- Feature #77: allow overriding global settings for each single request
+
 ## 1.10.2
 
 - Fixed #78: overriding header "Content-Type" not working on Android

README.md

@@ -100,7 +100,7 @@ If set to `true`, it won't follow redirects automatically. This is a global sett
 cordova.plugin.http.disableRedirect(true);
 ```
 
-### setDataSerializer
+### setDataSerializer<a name="setDataSerializer"></a>
 Set the data serializer which will be used for all future PATCH, POST and PUT requests. Takes a string representing the name of the serializer.
 
 ```js
@@ -183,6 +183,42 @@ Remove all cookies associated with a given URL.
 cordova.plugin.http.removeCookies(url, callback);
 ```
 
+### sendRequest
+Execute a HTTP request.  Takes a URL and an options object. This is the internally used implementation of the following shorthand functions ([post](#post), [get](#get), [put](#put), [patch](#patch), [delete](#delete), [head](#head), [uploadFile](#uploadFile) and [downloadFile](#downloadFile)). You can use this function, if you want to override global settings for each single request.
+
+The options object contains following keys:
+
+* `method`: HTTP method to be used, defaults to `get`, needs to be one of the following values:
+  * `get`, `post`, `put`, `patch`, `head`, `delete`, `upload`, `download`
+* `data`: payload to be send to the server (only applicable on `post`, `put` or `patch` methods)
+* `params`: query params to be appended to the URL (only applicable on `get`, `head`, `delete`, `upload` or `download` methods)
+* `serializer`: data serializer to be used (only applicable on `post`, `put` or `patch` methods), defaults to global serializer value, see [setDataSerializer](#setDataSerializer) for supported values
+* `timeout`: timeout value for the request in seconds, defaults to global timeout value
+* `headers`: headers object (key value pair), will be merged with global values
+* `filePath`: filePath to be used during upload and download see [uploadFile](#uploadFile) and [downloadFile](#downloadFile) for detailed information
+* `name`: name to be used during upload see [uploadFile](#uploadFile) for detailed information
+
+Here's a quick example:
+
+```js
+const options = {
+  method: 'post',
+  data: { id: 12, message: 'test' },
+  headers: { Authorization: 'OAuth2: token' }
+};
+
+cordova.plugin.http.sendRequest('https://google.com/', options, function(response) {
+  // prints 200
+  console.log(response.status);
+}, function(response) {
+  // prints 403
+  console.log(response.status);
+
+  //prints Permission denied
+  console.log(response.error);
+});
+```
+
 ### post<a name="post"></a>
 Execute a POST request.  Takes a URL, data, and headers.
 
@@ -241,7 +277,7 @@ Here's a quick example:
 }
 ```
 
-### get
+### get<a name="get"></a>
 Execute a GET request.  Takes a URL, parameters, and headers.  See the [post](#post) documentation for details on what is returned on success and failure.
 
 ```js
@@ -255,19 +291,19 @@ cordova.plugin.http.get('https://google.com/', {
 });
 ```
 
-### put
+### put<a name="put"></a>
 Execute a PUT request.  Takes a URL, data, and headers.  See the [post](#post) documentation for details on what is returned on success and failure.
 
-### patch
+### patch<a name="patch"></a>
 Execute a PATCH request.  Takes a URL, data, and headers.  See the [post](#post) documentation for details on what is returned on success and failure.
 
-### delete
+### delete<a name="delete"></a>
 Execute a DELETE request.  Takes a URL, parameters, and headers.  See the [post](#post) documentation for details on what is returned on success and failure.
 
-### head
+### head<a name="head"></a>
 Execute a HEAD request.  Takes a URL, parameters, and headers.  See the [post](#post) documentation for details on what is returned on success and failure.
 
-### uploadFile
+### uploadFile<a name="uploadFile"></a>
 Uploads a file saved on the device.  Takes a URL, parameters, headers, filePath, and the name of the parameter to pass the file along as.  See the [post](#post) documentation for details on what is returned on success and failure.
 
 ```js
@@ -281,7 +317,7 @@ cordova.plugin.http.uploadFile("https://google.com/", {
 });
 ```
 
-### downloadFile
+### downloadFile<a name="downloadFile"></a>
 Downloads a file and saves it to the device.  Takes a URL, parameters, headers, and a filePath.  See [post](#post) documentation for details on what is returned on failure.  On success this function returns a cordova [FileEntry object](http://cordova.apache.org/docs/en/3.3.0/cordova_file_file.md.html#FileEntry).
 
 ```js