R functions as self-documenting API’s.

R functions as APIs

In our first post we demonstrated how to publish an R function to OpenCPU, so that it comes an API that can be called remotely. In a subsequent post we showed the advantages of putting the function in a package: it gets a permanent URI and one can include ‘apps’ in the R package that interface to the function. In this post we show another advantage: documentation.

Help pages though OpenCPU

Nobody likes to write documentation. For many projects, documentation is very time consuming, and often lacks behind with the actual code. This holds even more so for web API’s. Because OpenCPU turns R functions automatically into API’s, the documentation for your R function is also the documentation for your API! This also allows you to leverage powerful tools like roxygen2 to create fast and easy documentation.

The new version of OpenCPU (beta2) makes R help files automatically available in a number of formats. For example, to get the help page for the liveplot function in the opencpu.demo package, open:

http://beta.opencpu.org/R/help/opencpu.demo/liveplot/text
http://beta.opencpu.org/R/help/opencpu.demo/liveplot/html
http://beta.opencpu.org/R/help/opencpu.demo/liveplot/pdf
http://beta.opencpu.org/R/help/opencpu.demo/liveplot/latex
http://beta.opencpu.org/R/help/opencpu.demo/liveplot/json

Based on the help files, it will be easy for clients to understand that the liveplot function has one parameter named ticker, which should match a valid stock ticker symbol. Hence the function can be called through e.g.

http://beta.opencpu.org/R/call/opencpu.demo/liveplot/png?ticker="AAPL"

We created and documented an API to create live plots by simply writing and documenting the R function. How easy was that? As always, the source code of the function is also available though OpenCPU:

http://beta.opencpu.org/R/call/base/identity/ascii?x=opencpu.demo::liveplot