Access All API Features With CloudRail’s Advanced Request
With CloudRail you can easily integrate external APIs into your application. CloudRail offers SDKs with abstracted interfaces that bundle several services to expose developer-friendly APIs that allow easy, native access to functionality independent of the underlying service. For example, this means that the upload() function to upload a file has the same signature for Dropbox as it does for Google Drive, OneDrive and other Cloud Storage Services. The same holds for the getEmail() function to get a user’s email address across all social networks and much more.
Normally developers integrate a CloudRail SDK into their application and access the predefined functions. If you do not know CloudRail yet you can learn more about available services, interfaces and standard usage at https://cloudrail.com/available-apis/. The interface functions give access to a subset of a service provider API’s functionalities which covers the most common use cases but sometimes this is not enough.
This article gives you an introduction to CloudRail’s newest feature, called Advanced Request. The feature’s main target audience are developers that are already using one or more services through a CloudRail integration but are missing a specific functionality. If that functionality is provided by a service’s API but by none of the CloudRail interfaces then Advanced Request is for you. The feature provides developers with an HTTP client “on steroids”. It allows you to specify your own HTTP requests towards the underlying API but supports you in many ways. It automatically prepends the base URL, takes care of authentication and does error checking for you. That way you can access all of an API’s functionality with only little more effort than using one of the functions of a CloudRail interface. Let us illustrate this with an example:
We want to list all shared folders of a Dropbox account. We look at the Dropbox API documentation and find that Dropbox supports this functionality (https://www.dropbox.com/developers/documentation/http/documentation#sharing-list_folders). Yet the CloudRail Dropbox service has no function to get this list so we use Advanced Request. We assume that you are already familiar with the installation of CloudRail and the initialization of a service.
Now we have a list of the required shared folders and can work with it.
As of February 27th 2017, all CloudRail interfaces support Advanced Request.
You can fully customize the requests which means you can specify the HTTP method (default is GET) and URL. It is possible for you to set the headers as well as the body. You can pass the body as a stream, a string or a JSON/XML object. If you want to add query parameters you should append them directly to the URL.
Advanced Request makes your requests easier by prepending a Base URL, adding authorization and doing error checking. This assumes that all API endpoints behave similarly in these regards which sometimes is not the case. You might have to disable authentication and do it on your own, e.g. because insufficient scopes are requested. For some endpoints you might have to disable error checking or do additional checking because the defaults are wrong or not enough. Or you might have to disable prepending the base URL because a certain API endpoint uses a different one. Do read up on each service in the respective documentation to learn about what base URL is prepended, what authorization appending does and which errors are caught.
Moreover, if you use the Advanced Request feature you specify a service specific functionality which can hurt the easy replaceability of that service by another one from the same interface. Yet if you are using the feature you probably do so to access a functionality that not all of the services implementing an interface support anyway, so this might not be an issue for you.