Update http-requests.md

Author: britzl

docs/en/manuals/http-requests.md

@@ -41,9 +41,80 @@ local body = "foo=bar"
 http.request("https://httpbin.org/post", "POST", handle_response, headers, body)
 ```
 
+
 ### Other HTTP methods
 
-Defold HTTP requests also support the HEAD, DELETE and PUT methods.
+Defold HTTP requests also support the HEAD, DELETE and PUT methods. The CONNECT method is also supported (see section about proxy connections).
+
+
+### How to work with the HTTP response
+
+The `response` table returned in the callback contains all of the information necessary to implement granular reponse handling. Two of the key fields are `status` and `response`:
+
+```lua
+
+local function handle_response(self, id, response)
+	-- check the response status code. Common response codes:
+	-- 200 OK - the request completed successfully
+	-- 301 Moved permanently - the requested data has moved, see redirect header
+	-- 307 Temporary redirect - same as above
+	-- 208 Permanent redirect - same as above
+	-- 400 Bad Request - the request was malformed
+	-- 401 Unauthorized - the client must authenticate itself
+	-- 404 Not Found - the server cannot find the information
+	-- https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status
+	if response.status == 200 then
+		-- the response data
+		-- this can be anything from plain text, json encoded data or binary data
+		print(response.response)
+		json.decode(response.response)
+		sys.save(..., response.response)
+	end
+end
+```
+
+When the response contains a large blob of binary data such as an image or a music track it might make sense to write the data to a file instead of loading it into memory:
+
+```lua
+-- in this example we download myimage.png and write it directly to a file on disk
+
+local options = {
+	path = sys.get_save_file("mygame", "myimage.png")
+}
+
+local function handle_response(self, id, response)
+	if response.status == 200 then
+		print("File was successfully written to:", response.path)
+		print("File size:", response.document_size)
+	else
+		print("File was not written to disk:", response.error)
+	end
+end
+
+http.request("https://www.foobar.com/myimage.png", "GET", handle_response)
+```
+
+Another use-case for loading large amounts of data over the network is sound streaming, when "chunks" of sound data are loaded from a URL and fed into a sound resource. A complete example can be found in the [Sound Streaming manual](/sound-streaming#sound-streaming).
+
+
+### HTTP Proxy
+
+It is sometimes desirable to send a request through a proxy server. This can be done by specifying a proxy server to use when connecting to the destination server. When a proxy is used the connection to the destination server is established using an a HTTP tunnel through the proxy. The HTTP tunnel is established using the CONNECT HTTP method. Example:
+
+
+```lua
+-- connect to www.defold.com via localhost proxy on port 8888
+local url = "https://www.defold.com:443"
+local method = "GET"
+local headers = {}
+local post_data = nil
+local options = {
+	proxy = "https://127.0.0.1:8888"
+}
+http.request(url, method, function(self, id, response)
+	pprint(response)
+end, headers, post_data, options)
+```
 
 ### API Reference