Let’s Rapplicate!

January 2, 2013

(This article was first published on rapporter, and kindly contributed to R-bloggers)

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:
New Rapplication form

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

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.

Rapplications API

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):
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).

Rapplications DIY

S’il vous plaît, we hacked in a plain HTML form for you. Please choose a variable from the well-know mtcars dataset and click on the Show me the report! button.

Descriptive statistics run on mtcars

If you’re interested, here’s the source of previous form:
<form name="rapporter" method="POST" action="https://rapporter.net/api/rapplicate" target="_blank">
<legend>Descriptive statistics run on <code>mtcarscode>legend>
<select name="var">
<option value="mpg">Miles/(US) gallonoption>
<option value="cyl">Number of cylindersoption>
<option value="disp">Displacement (cu.in.)option>
<option value="hp">Gross horsepoweroption>
<option value="drat">Rear axle ratiooption>
<option value="wt" selected="selected">Weight (lb/1000)option>
<option value="qsec">1/4 mile timeoption>
<option value="vs">V/Soption>
<option value="am">Transmission (0 = automatic, 1 = manual)option>
<option value="gear">Number of forward gearsoption>
<option value="carb">Number of carburetorsoption>
<input type="hidden" name="token" value="d9d6c2dadf723bbb55537e776db2c72bf6f679f9647591a7dd693b7abac93304">
<input type="submit" class="button" id="submit_btn" value="Show me the report!" />
As you can see, it’s pretty straightforward to roll your own stuff, just make sure to add a proper token value in the hidden input, and hunt down the appropriate dataset input values. Once again, we’re doing that for you in our bundled