• Home
• Felgo
• HttpRequest

HttpRequest

Allows to implement networking features based on the SuperAgent library from VisionMedia. More...

• List of all members, including inherited members

Properties

• cookie : var

Methods

• void clearCookies()
• void config(var options)
• var del(string url, var callback)
• var get(string url, var data, var callback)
• var head(string url, var data, var callback)
• var patch(string url, var data, var callback)
• var post(string url, var data, var callback)
• var put(string url, var data, var callback)

Detailed Description

The Felgo HttpRequest type integrates DuperAgent, a QML clone of the fantastic SuperAgent library from VisionMedia. The library is implemented in Qt/C++ and designed as an alternative to QML's builtin implementation of XmlHttpRequest.

The component is available as a singleton item and usable from all QML components that import Felgo via import Felgo.

Features

• Modern API in comparison to XmlHttpRequest
• Support for multipart/form uploads
• Automatic parsing of response bodies with known content-types
• Built-in persistent cookie jar
• Promise API
• Secure connection (SSL/TLS) API
• Network activity indicator
• Image utilities
• Return an object with error information in case the request fails

The currently used Duperagent version is v1.5.0.

Example Usage

The QML API is almost identical to the JS API of SuperAgent. See the SuperAgent documentation for more API examples.

The following functions are not yet available with the DuperAgent QML port:

• withCredentials: CORS - Not implemented
• buffer: Response body buffering is not yet implemented
• pipe: Piping to streams is not supported

Get Request

Use the HttpRequest::get() method to create a new request object. The returned object then allows to specify additional request settings or send the request. For example, use the timeout function to specify the maximum request timeout. With a call of the then or end function you can send the request and handle the result.

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest
       .get("http://httpbin.org/get")
       .timeout(5000)
       .then(function(res) {
         console.log(res.status);
         console.log(JSON.stringify(res.header, null, 4));
         console.log(JSON.stringify(res.body, null, 4));
       })
       .catch(function(err) {
         console.log(err.code)
       });
   }
 }

This is how the same code looks like using the end() function:

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest
       .get("http://httpbin.org/get")
       .timeout(5000)
       .end(function(err, res) {
         if(res.ok) {
           console.log(res.status);
           console.log(JSON.stringify(res.header, null, 4));
           console.log(JSON.stringify(res.body, null, 4));
         }
         else {
           console.log(err.message)
           console.log(err.response.text)
         }
       });
   }
 }

DELETE, HEAD, PATCH, POST, and PUT requests are also available with a simple change of the method name.

Post Request

A typical JSON POST request might look a little like the following, where we set the Content-Type header field appropriately, and "write" some data, in this case just a JSON string:

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest
       .post("https://jsonplaceholder.typicode.com/posts")
       .set('Content-Type', 'application/json')
       .send({ title: "post title", body: "post body" })
       .then(function(res) {
         console.log(res.status);
         console.log(JSON.stringify(res.header, null, 4));
         console.log(JSON.stringify(res.body, null, 4));
       })
       .catch(function(err) {
         console.log(err.code)
       });
   }
 }

Since JSON is undoubtedly the most common, it's the default Content-Type setting. You can also split the data into multiple send() calls:

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest
       .post("https://jsonplaceholder.typicode.com/posts")
       .send({ title: "post title" })
       .send({ body: "post body" })
       .then(function(res) {
         console.log(res.status);
         console.log(JSON.stringify(res.header, null, 4));
         console.log(JSON.stringify(res.body, null, 4));
       })
       .catch(function(err) {
         console.log(err.code)
       });
   }
 }

For more information on the http features of SuperAgent, please see their documentation.

Additional Request Features

The HttpRequest methods like get() or post() present you with a request object. But the request is not sent right away. You can specify additional settings for the request, before you send it and handle the result with the then or end function. You can use this to e.g specify a timeout or activate caching.

Caching API of DuperAgent

The caching API of HttpRequest is super useful to locally cache results of your requests as fallback in case of network or server issues.

To set up the cache, you can use the config() method:

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest.config({
       cache: true
     });
   }
 }

By default the cache is active and not limited in size. To deactivate the cache, set a maximum size or change the cache location, see the config() options. You can also change the caching behavior of individual HttpRequest items with the following methods:

• var cacheSave(boolean)

  Overrides the cache save behavior for a single request. Setting it to true will enable caching, while false deactivates the cache.

• var cacheLoad(HttpCacheControl)

  This function is set to override the cache load behavior for a single request. It can have the following values:

  • HttpCacheControl.AlwaysNetwork
  • HttpCacheControl.PreferNetwork (default)
  • HttpCacheControl.PreferCache
  • HttpCacheControl.AlwaysCache

You can use them as shown in this example:

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest
       .get("http://httpbin.org/get")
       .cacheSave(true) // cache the result of this request, regardless of global cache setting
       .cacheLoad(HttpCacheControl.PreferNetwork) // use network if possible, otherwise load from cache
       .then(function(res) {
         console.log(JSON.stringify(res.body))
       })
       .catch(function(err) {
         console.log(err.code)
       });
   }
 }

Upload Files as Attachment

The following snippet shows how to attach files to the HttpRequest object.

 Item {
   function uploadFile(serverUrl, fileName, fileUrl, callback) {
     HttpRequest.post(serverUrl)
     .attach("file", fileUrl, fileName)
     .end(function(err, res) {
       if(res.ok) {
         // upload successful
         let responseData = res.body
       }
       else {
         // upload failed
         console.error("Error: " + err.message)
       }
     });
   }
 }

Authentication, Timeouts and More

The request object you receive from e.g. HttpRequest::get or HttpRequest::post offers many functions for additional features and configurations. For example, the cacheSave, cacheLoad, timeout or attach features that are used in the above code samples.

The API for the request object matches VisionMedia's SuperAgent library for JavaScript. The following methods are supported:

• var use(var fn)
• var timeout(int ms)
• var clearTimeout()
• var abort()
• var set(var field, var val)
• var unset(var field)
• var type(var type)
• var accept(var type)
• var auth(string user, string password)
• var redirects(int redirects)
• var cacheSave(bool enabled)
• var cacheLoad(int value)
• var query(var query)
• var field(var name, var value)
• var attach(var name, var path, var filename)
• var send(var data)
• var withCredentials()
• var on(var event, var handler)
• var end(var callback)
• var then(var onFulfilled, var onRejected)

Please see the SuperAgent documentation for more information and usage examples.

Promises, Image Utils and Activity Indicator

Similar to HttpRequest, which matches the DuperAgent Request type, other DuperAgent components are also directly available in Felgo:

• Promise - Execute several requests and handle the result depending on whether all or any of the requests succeeded.
• HttpNetworkActivityIndicator - Allows to check for pending requests of HttpRequest, using HttpNetworkActivityIndicator::enabled.
• HttpImageUtils - Provides functionality for scaling and cropping an image file before uploading it via DuperAgent's attach function.

Promise API of DuperAgent

The DuperAgent package also contains an implementation of the Promises/A+ specification and offers an API similar to the Promises API in ES2017. For more information, please see MDN.

The Promise type works independently of DuperAgent's http features and does not require the Http prefix. This is how you can create a Promise in QML to handle the result of an HttpRequest:

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {

     var p = Promise.create(function(resolve, reject) {
       // handle asynchronous code here
       // e.g. with asynchronous HttpRequest
       HttpRequest
         .get("http://httpbin.org/get")
         .timeout(5000)
         .end(function (err, res) {
           if(res.ok)
             resolve(res.body)
           else
             reject(err.message)
         })
     });

     // execute promise and handle result
     p.then(function(value) {
        // success
       console.log("Value: "+JSON.stringify(value))
     }).catch(function(reason) {
       // failure
       console.log("Error: "+reason)
     });

   }
 }

Multiple HttpRequests with Promise, Caching and Activity Indicator

The following example combines multiple http requests with a promise, caching and an activity indicator:

 import Felgo
 import QtQuick

 App {

   Component.onCompleted: {
     // remove activation delay to immediately show the indicator for requests
     // otherwise, requests that take less than the default 150 ms won't trigger the indicator
     HttpNetworkActivityIndicator.activationDelay = 0

     // configure caching
     HttpRequest.config({
       cache: { maxSize: 20000 } // max size of 200000 bytes
     })
   }

   NavigationStack {
     AppPage {
       id: myPage
       title: "HttpRequest Example"
       rightBarItem: ActivityIndicatorBarItem {
         animating: HttpNetworkActivityIndicator.enabled
         visible: animating
       }

       // HttpNetworkActivityIndicator is not supported with Promises
       // this example thus uses a custom activity indicator handling
       property bool promisePending: false

       // function to send all requests and handle the result
       function sendAllRequests() {
         // trigger first request
         var p1 = HttpRequest
           .get("https://jsonplaceholder.typicode.com/todos/1")
           .cacheSave(false) // do not save response of first request to cache
           .cacheLoad(HttpCacheControl.AlwaysNetwork) // always load from network
           .then(function(res){ return res.body; });

         // trigger second request
         var p2 = HttpRequest
           .get("https://jsonplaceholder.typicode.com/posts/1")
           .timeout(5000)
           .cacheLoad(HttpCacheControl.PreferCache) // use cache if possible, otherwise load from network
           .then(function(res){ return res.body; });

         // create promise to check success of both requests
         var allRequests = Promise.all([p1, p2])

         // handle promise result
         allRequests.then(function(values) {
           console.log("Both requests finished: "+JSON.stringify(values))
         }).catch(function (err) {
           console.log("Error: "+err)
         })
       }

       AppButton {
         text: "Send Get Requests"
         anchors.centerIn: parent
         onClicked: myPage.sendAllRequests()
       }
     }
   }
 }

Return an object with error information

The following example returns an object with error information in case the request fails and prints result:

 import Felgo
 import QtQuick
 App {
   Component.onCompleted: {
     HttpRequest
       .get("http://localhost:3002/test")
       .timeout(5000)
       .end(function(err, res) {
         if(res.ok) {
           console.log(res.status);
           console.log(JSON.stringify(res.header, null, 4));
           console.log(JSON.stringify(res.body, null, 4));
         }
         else {
            console.log("response", JSON.stringify(err.response))
         }
       });
   }
 }

Property Documentation

Method Documentation

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest.config({
       cache: false
     });
   }
 }

 import Felgo
 import QtQuick

 App {
   Component.onCompleted: {
     HttpRequest
       .get("http://httpbin.org/get")
       .timeout(5000)
       .end(function(err, res) {
         if(res.ok) {
           console.log(res.status);
           console.log(JSON.stringify(res.header, null, 4));
           console.log(JSON.stringify(res.body, null, 4));
         }
         else {
           console.log(err.message)
           console.log(err.response.text)
         }
       });
   }
 }