Let’s Rapplicate!

It’s been a while since you last heard from Rapporter, and we came up with a (hopefully) good excuse for our absence from the blogosphere: Rapplications. To demystify: we developed an API that allows you to create dynamic reports by using the R templates and datasets available on Rapporter. All you need is an account on Rapporter (you can get it here) and of course an access to some templates and datasets in there.

Once you’re logged in click on Settings > Rapplications > New, or simply visit this link. You should see a form similar to this one:

Title and Description fields are pretty self-explanatory. In the Referer field you can add newline-separated list of Ruby regular expressions to restrict access to your Rapplication from a desired set of URLs, while blank field (default) sets no restrictions. Proceed and select a  Template and optionally a Dataset if the template could use one, then click on Create Rapplication.

In Output format field you can choose between various document types – currently we support: PDF, DOCX, ODT, HTML, and partial HTML (which returns just rendered report, and not the full HTML page). If everything goes fine, a new Rapplication will be created, a unique Token will be assigned to it, and you’ll see something like this:

Rapplication details

In case you want some instant gratification, you can grab the <iframe> code from the bottom of the page and include it in your website. Once you do that, HTML form will be rendered, so that you can map inputs defined in the template against the variables available in the dataset. Try out the live form below and generate your report (or visit the page directly if your RSS reader blocked the <iframe> part):

So go ahead and provide required inputs, click on Show report when you’re done, and depending on the dataset size and calculation complexity, you’ll be soon served a report in the desired document format. And for that one to happen, you don’t even need to be logged in Rapporter. Pretty neat, huh?

But that’s just a convenience wrapper with a clickity-click user interface. We’re pre-populating the form inputs with the appropriate dataset variable names and/or input values, so you don’t have to.

Anyway, remember that there’s an API behind this? PoweR useRs, stay tuned, you may like what comes next.

The Token assigned to your Rapplication is the crucial piece of information needed for further hacking (d’uh). Once it’s created, Rapplication saves selected dataset and template under the unique token.  If you know the names of inputs, you can easily send POST/GET request via cURL or your preferred REST tool to generate rendered reports in the desired document format. For instance, if your template has numeric variable inputs x and y, and your dataset has variables a and b to match the given inputs, you can send GET request like this (assuming, of course, that you have provided a correct Token value):

https://rapporter.net/api/rapplicate/?token=12345&x=a&y=b&output_format=pdf

Output format can be omitted from the request query, and in that case Rapplication-defined value is used (defaults to PDF). Currently valid output_format values are: pdf, docx, odt, html, and html-partial.

And a note of caution: before you Rapplicate, please make sure that your referer URL matches the defined rules (if any) – it’s a common pitfall, at least from our experience.

You can also send POST request and shove the parameters in the BODY instead. Here’s an example with cURL, we’ll be using Beta distribution template, pass some inputs and get ODT file as a result:

curl -o beta-distrib-test.odt -d token\=d284d1e8680ca42ab816ac1d54e67a8f75a1ceefda63d7f961e7b71c28d50038\&n\=100\&shape1\=2\&shape2\=3\&output_format\=odt https://rapporter.net/api/rapplicate/

Upon successful request, output file will be sent with response code 200, and in case of query error (e.g. incorrect Token or parameters), response code 400 will be returned along with the fancy error notice (though not as fancy as GitHub’s Star Wars flavoured Octocat).