Arelle’ web service API, based on REST, provides XBRL services to non-Python applications, such as Excel, Java, and C#.

The web services can operate as a stand-alone single-process web server, or can operate under another web server.  When operating stand-alone and in a single-process, Arelle can interact with multiple interfaces and requests without reloading its object model, such as QuickBooks XBRL-GL interfaces or separate API requests to perform subsequent operations on the same object model.  When operating under an independent web server (such as IIS or Apache) the examples below have each REST API request handled as an independent request in an independent process, using CGI, which is suitable for a production environment.  In each of these Arelle operates from its compiled binary application, without requiring installing of Python and python library packages within the web server.

To start as a simple stand-alone web server (where the Arelle executable handles the web service requests itself, e.g., without using IIS or Apache):

• Windows:  Start menu->programs->Arelle->Start Web Server, scripts\startWebServer.bat, or ArelleCmdLine.exe –webserver locahost:8080
• Mac/OS: double-click startWebServer.command

The default port is “localhost:8080”.  The windows port can be changed by editing properties of the “Start Web Server” menu shortcut, .bat/.command file, or command line parameter.  The web server is terminated by cntrl-C to the webserver’s window.

The simple stand-alone web server REST API starts with “/”, so REST APIs start with the path http://localhost:8080/rest/xbrl/..., or help is at http://localhost:8080/help

The next two options provide Arelle’s REST API using web servers like IIS or Apache, invoking Arelle from the compiled binary application distribution for each.
To start as a CGI process under IIS, where each request will run as an independent process:

• Install the Windows executable.  arelleCmdLine.exe will detect when it is running as a CGI.
• Install IIS features for CGI (if not yet present in IIS).
• Add a web site for the CGI, with its own port number (such as 8080), an application pool, advanced settings physical path to C:\Program Files\Arelle (or your installation location).  Set permissions on that directory (such as Everyone or IIS processes, so they can write the web.config directory and any other files as needed).
• Set application pool framework version at 2.0, and maximum worker processes at number of CPU cores available (under advanced properties).
• Add handler mapping for Arelle, similar to this, using * so REST paths to go into Arelle:
  • Request path: *
  • Executable: “C:\Program Files\Arelle\arelleCmdLine.exe” %s
  • Name: Arelle
  • Arelle’s cache directory for IIS defaults to

  C:\Windows\Temp\Arelle

  • , and is created on initial startup for you. This can be confirmed by REST API

  /rest/configure?environment

  . If you copy into this directory be sure to set permissions, such as IUSR.

This IIS web server configuration REST API starts with “/”, so REST APIs start with the path http://localhost:8080/rest/xbrl/...

Here are contributed steps by another user to set up Arelle under IIS:

1.For security reasons every CGI has to be registered in the ISAPI/CGI Restriction list: Right click on Web server name and double click on ISAPI and CGI Restrictions. Add C:\ArelleCGI\arelleCmdLine.exe with desc: arelleCmdLine and check “Allow extension path to execute”

2.Create web site with port number pointing to c:\ArelleInstallFolder(and or virtual directory under existing web site or newly created). If a web site is created it will by default assign AppPoolIDForOurApp as the security identity
under which the new web server will run.

We still don’t allow “Execute” access in this directory. For this you have to go to the Handler Mappings menu of the CGI virtual directory (make sure you select the CGI virtual directory on the left hand side!).

Go to the “Edit Feature Permissions” link in the Actions Menu on the right hand side, open it and check “Execute” and click “OK”.

3.Double click on CGI-exe in Handler Mappings (default name of the mapping that we enabled in step 2, but it needs to be configured) to edit this mapping
Request path = *.exe
Executable = C:\ArelleIISCGI\arelleCmdLine.exe %s –xdgConfigHome=”C:\ArelleIISCGI\cache”

4.We need to add IIS APPPOOL\AppPoolIDForOurApp account to the physical folder where Arelle was installe e.g. c:\ArelleInstallFolder (default permissions read are fine – since we are not writing to it.)

5.Modify IIS APPPOOL\AppPoolIDForOurApp permissions on c:\ArelleInstallFolder\cache folder (or whatever folder will be used to store Arelle config and cache) to include write permissions (read permissions are fine if we have cache already, but if we are able to get through the proxy or we have open access to the Internet write access is needed)

To start as a CGI installed under an Apache web server, where each request will run as a separate process:

• Ensure that the web server has mod-cgi installed and a working cgi directory (such as /usr/lib/cgi-bin, as with Ubuntu).  Do not specify AcceptPathInfo (otherwise it will block the REST path following arelleCmdLine in the URL path).
• Unzip the Linux executable within the mod-cgi directory (such as to a subdirectory arelle, so the path to arelleCmdLine is /usr/lib/cgi-bin/arelle/arelleCmdLine).  Ensure permissions will allow the web server to access the directory and execute.  The executable arelleCmdLine detects when it is running as a CGI instead of from a command script or shell.
• Arelle needs a cache directory.  With Ubuntu this defaults to /var/www/.config/arelle.  Create those directories (probably needs sudo) and set their owners and groups (with Ubuntu user and group are set to www-data).

This Apache web server configuration REST API starts with /cgi-bin/arelle/arelleCmdLine, so REST APIs start with the path http://myhost.com/cgi-bin/arelle/arelleCmdLine/rest/xbrl/..., or help is at http://myhost.com/cgi-bin/arelle/arelleCmdLine/help

(There are other alternatives to running Arelle as a stand-alone single-process web server or running from compiled binary application distribution.  The single-process mode can use other servers supported by Python Bottle, some of which, like CherryPy, have multi-processing support.  The source code supports use as an WSGI application (automatically detected on start up of arelleCmdLine.py), which can be deployed in a web server which has managed Python support and source code integration expertise.  The Python 2.7 version of Arelle has been installed on Google App Engine (GAE), such as for api.arelle.org.)

Below is a table of the API from Arelle’s web service.  API implemented by the installed version of Arelle is obtained by starting Arelle’s web services and clicking (or entering this link to your browser – it assumes use of the default port, 8080): http://localhost:8080/help.

Web Service API

tr>

Java integration sample (load and validate)

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class LoadValidate {
 public static void main(String[] args) throws IOException {
  String restAPIstr =
   "http://localhost:8080/rest/xbrl/" +
   "C:/Users/John%20Doe/Samples/instance0010000.xbrl" +
   "/validation/xbrl?media=text";
  URL url = new URL(restAPIstr);
  HttpURLConnection conn =
        (HttpURLConnection) url.openConnection();

  if (conn.getResponseCode() != 200) {
      throw new IOException(conn.getResponseMessage());
  }

  // Buffer the result into a string
  BufferedReader rd = new BufferedReader(
        new InputStreamReader(conn.getInputStream()));
  StringBuilder sb = new StringBuilder();
  String line;
  while 1)line = rd.readLine( != null) {
      sb.append(line);
   System.out.println(line);
  }
  rd.close();
  conn.disconnect();
 }
}

C# integration sample (load and validate)

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Diagnostics;

namespace ArelleCsharpProject
{
    class LoadValidate
    {
        static void Main(string[] args)
        {
      string restAPIstr =
       "http://localhost:8080/rest/xbrl/" +
       "C:/Users/John%20Doe/Samples/instance0010000.xbrl" +
       "/validation/xbrl?media=text";

            HttpWebRequest req = WebRequest.Create(restAPIstr) as HttpWebRequest;

            string line;
            using (HttpWebResponse resp = req.GetResponse() as HttpWebResponse)
            {
                StreamReader reader = new StreamReader(resp.GetResponseStream());
                while 2)line = reader.ReadLine( != null)
                    Debug.WriteLine(line);
            }
        }
    }
}