Chapter 8. Server API

Table of Contents

Overview
REST
JDBC
Calling HTTP
JavaScript Extensions

Overview

Elixir Repertoire Server is accessible and manageable through the Hypertext Transport Protocol (HTTP), the kind of network connection used by a browser when accessing an http: or https: web site. We've already seen the browser interface provided by the server in Chapter 6, Web Interface, in this chapter we will look at how the server URLs can be used to interact with the tool through programs.

The HTTP protocol specifies Uniform Resource Locators, like http://www.elixirtech.com/ and operations GET, POST, PUT and DELETE. Browsers typically use GET for reading web pages and POST for submitting data, such as entry forms. Each operation has characteristics defined by the HTTP standard, so that all software that uses HTTP can follow the same rules.

GET
Getting a resource can be performed at any time, and as many times as necessary. It has no side-effects, so calling GET again is perfectly safe - just like keep hitting refresh on your browser. It is like coding PRINT X. X won't change, however many times you call it. Many tools have a limit on the size of a URL, so a GET with a long parameter string can occasionally cause an error. Therefore some Report and Data services that should logically be GET services are also provided as POST services because POST has no artificial limit on parameter size. These services will be noted below as "GET or POST" - you will find the GET version simpler to test from a browser, but might need to use the POST version in the rare case that the total size of your parameters exceeds a few kB.
POST
Posting should be used with care as these methods do have side-effects. For example on a website when you book a flight, you shouldn't submit (POST) twice, or you will probably get billed twice. It is like coding X = X + 1. Every time you call it X ends up with a different value.
PUT
Putting a resource can be performed at any time. This method created or updates the value of a resource. You can repeat the operation and there are no side-effects. It is like saying X = 5. You can say it as many times as you want. After the first time, it has no extra effect.
DELETE
Deleting a resource can be performed at any time. You can repeat the operation and there are no side-effects. This is because you can safely delete something that isn't there - it isn't an error, the result is, it still isn't there. Following our coding analogy, this is like coding X = NULL.

HTTP provides the basic data interchange protocols, but there are a variety of mechanisms used on top of these four primitive operations. Elixir Repertoire Server uses Representational State Transfer (REST).

Logon

Service: POST /logon.html
  • Parameter: username
  • Parameter: password
  • Parameter: return (optional)

Explicit logon to the server, just like a user with a browser would do. API users should probably use the BASIC AUTH method of connection instead as this means the credentials are associated with each request and there will be no chance of a session timeout. A timeout would result in a redirect to the logon page, just like in the browser. Use return=SomeURL to redirect to a specific page if successful.

Service: GET /logout.html

Calling this URL invalidates the current session. Even if you don't explicitly logout, your session will expire within a fixed interval (default 100 mins). You will need to logon or supply BASIC AUTH credentials to continue using services.

Service: GET /authenticate-session
  • Parameter: session
  • Parameter: return (optional)

This URL supports the Single Sign-On (SSO) mechanism. The controlling server should logon to the Elixir Server using either /logon.html or BASIC AUTH and obtain a session cookie. The controlling server then redirects the user to this service, passing in the session id as a parameter. If the session id is valid, the authentication details will be cloned into a new session cookie returned directly to the user. The user may now continue to use the services without the intervention of the controlling server. If the controlling server logs off (/logout.html) providing the original session id, then any user session that was authenticated based on that session id will also be terminated.

Repository

Service: GET /repository
  • Parameter: mode (optional)

Provides a repository browser if no mode is supplied. The browser shows a single level of the tree with the ability to navigate through the children or return to the parent folder. Selecting a file will "open" the file - that means if it is text, html or pdf it will probably be streamed to your browser. If it is an rml, ds or pml you will probably be prompted to save it. Note that this provides access to the raw files - you can't render or generate from here. Other services provide that ability. If mode is "xml" then the filesystems are returned as XML. If mode is "tree" then the entire repository tree is returned in XML. The modified attributes indicate the last modified times of the files represented as the difference, measured in milliseconds, between the file time and midnight, January 1, 1970 UTC.

Response:

<!-- output when mode=xml -->
<filesystems>
  <filesystem displayName="ElixirSamples"/>
  <filesystem displayName="Scheduler"/>
</filesystems>

<!-- output when mode=tree -->
<repository>
  <folder name="ElixirSamples" 
      modified="1179946379812" access="rw">
    <folder name="Dashboard" 
        modified="1179946365312" access="rw">
      <folder name="Border Catalog" 
          modified="1180009266296" access="rw">
        <file name="All Borders.ds" 
            modified="1179946257296" access="rw"/>
        <file name="All Borders.rml" 
            modified="1179946300875" access="rw"/>
        ...
Service: GET /repository/ElixirSamples/Report
  • Parameter: mode (optional)

This is a continuation of the previous service, as you navigate through the HTML, the service URL changes to mirror the repository file structure. You can use the same mode options, "xml" and "tree", which give you the corresponding output, but rooted on the repository path identified in the URL.

Service: GET /repository/ElixirSamples/Report/CustomerListing.rml

This is a continuation of the previous two services and illustrates the retrieval of a file. In this case, mode is not used as the file will always be returned using its original mime-type. Again, note that this will download the CustomerListing report template, it won't render the report. See the Report and Target services below for rendering options.

Service: PUT /repository/ElixirSamples
  • Parameter: action
  • Parameter: mode

Update the filesystem. By entering "update" and "filesystem" for the parameters named "action" and "mode" respectively will update the filesystem specified in the java file.

Service: PUT /repository/ElixirSamples/Report/CustomerListing.rml

Set the file contents. If the name doesn't exist, then a new file will be created, or a new folder if the pathname ends with '/'.

Service: DELETE /repository/ElixirSamples/Report/CustomerListing.rml

Delete the file or folder (along with any child files and folder).

Service: POST /repository/ElixirSamples/Report/CustomerListing.rml
  • Parameter: action
  • Parameter: to (optional)

This service provides utility options for repository management. When the path points to a file or folder and the action is "rename" and to is another filename, the file or folder will be renamed (retaining the same parent). When the path points to a filesystem and the action is "refresh", then that filesystem is refreshed. When the path points to /repository and the action is "refresh" then all filesystems are refreshed.

Task

Service: GET /tool/admin/tasks.html

Displays the loading status of reports and datasources. When loading completes, the task is removed from the list.

Query

Service: GET /query/alive

Tests if the server is alive and responding to requests.

Response:

200 (Ok) if the server is alive
Service: GET /query/mime-types

Get the mime-types supported for rendering.

Response:

<mime-types>
  <mime-type name="application/pdf"/>
  <mime-type name="application/postscript"/>
  <mime-type name="application/rtf"/>
  ..
Service: GET /query/targets

Get the available targets for rendering to, along with the default target properties that you can override.

Response:

<targets>
  <target name="mail">
    <property name="message">Your report is attached.</property>
    <property name="to">elided...alice@example.com</property>
    <property name="subject">Report from Elixir Server</property>
    <property name="smtp.host">elixir.aspirin</property>
    <property name="filename">report</property>
    <property name="from">tom@example.com</property>
    <property name="cc">elided...susan@example.com</property>
  </target>
  <target name="db">
    <property name="overwrite">yes</property>
    <property name="driver">elided...EmbeddedDriver</property>
    <property name="table">JobOutput</property>
    <property name="url">jdbc:derby:C:/Temp/elxdb/fs</property>
  </target>
  ...
Service: GET /query/filesystems

Get the filesystems visible to the user.

Response:

<filesystems>
  <filesystem display-name="ElixirSamples" 
    configuration="C:\RepertoireServer\samples" 
    read-only="false" type="local"/>
  <filesystem display-name="Scheduler" 
    configuration="Scheduler" 
    read-only="false" type="jdbc"/>
</filesystems>
Service: GET /query/jdbc-drivers

Get the JDBC drivers available on the server. This service will only return available known drivers - i.e. those with known classnames that are provided by the GUI as suggestions and marked with a green icon indicating they are available.

Response:

<drivers>
  <driver name="Derby Embedded" 
    class="org.apache.derby.jdbc.EmbeddedDriver"
    url="jdbc:derby:database"/>
  <driver name="JDBC/ODBC_Bridge (Sun JVM)" 
    class="sun.jdbc.odbc.JdbcOdbcDriver" 
    url="jdbc:odbc:Sample"/>
  <driver name="MySQL (com.mysql)" 
    class="com.mysql.jdbc.Driver" 
    url="jdbc:mysql://<host>/dbname"/>
  <driver name="MySQL (mm.mysql)" 
    class="org.gjt.mm.mysql.Driver" 
    url="jdbc:mysql://<host>/dbname"/>
</drivers>
Service: GET /query/repository/ElixirSamples/Report/CustomerListing.rml?mode=params

Gets the parameters for reports, datasources, dashboards and jobs

Response:

<!-- in this case there aren't any -->
<parameters report="/ElixirSamples/Report/CustomerListing.rml"/>

<!-- in this case there are -->
<parameters report="/ElixirSamples/Report/NewsToday.rml">
  <parameter>
    <key>Language</key>
      <type>choice(Mixed,Korean,Tamil,Arabic)</type>
      <value>Mixed</value>
   </parameter>
</parameters>
Service: GET /query/user

Get the current user information (id, name, groups).

Response:

<user name="admin" id="1" is-admin="Yes">
  <group id="1" name="admin"/>
  <group id="2" name="*"/>
</user>

Tool

Service: GET /tool/repository

Get the clickable repository tree (breadcrumbs flat HTML) that will open chosen files. This is different from the /repository URL in that it will launch the right engine to handle the Elixir file types - for example selecting a report will render it, selecting a datasource will generate the data and selecting a dashboard will open it for viewing. This is the URL that the shows below the menu bar when you log on to the Web Interface.

Remote

Service: GET /remote/license

Get the Remote license for the current (logged on) user. This license indicates what features of the Remote tool the user has access to.

Report

Service: GET or POST /report/ElixirSamples/Report/CustomerListing.rml
  • Parameter: mime-type
  • Parameter: elx.disposition
  • Parameter: any report parameters (optional)

Render the report into CSV, DocX, Excel, Glint, IML, PDF, PPTX and XML mime-types. The report will be streamed back to the client. Because this is a simple GET method, you can try this directly from your browser or embed a link into any web page. The data will be streamed back to your browser, which will show it directly in the specified mime-type. For "elx.disposition", it is specifically for the PDF mime-type, and there are only two options available. They are "inline" and "attachment". For "inline", the PDF will open in the window. As for "attachment", the user will be prompted to open or save the file. The POST version should be used if sending more than about 4kB of parameters.

Dashboard

Service: GET /dashboard/ElixirSamples/Dashboard/Operational Dashboard/Operational Dashboard.pml
  • Parameter: mode
  • Parameter: card
  • Parameter: any dashboard or datasource parameters (optional)

Returns the dashboard at the specified card with parameters entered if any. The options available for mode are "init" and "parameters".

Data

Service: GET or POST /data/ElixirSamples/DataSource/CustomerListing.ds
  • Parameter: mime-type
  • Parameter: any data source parameters (optional)
  • Parameter: xslt=respository:/some/file.xslt (optional)

Generate the data into the requested mime-type. The available mime-types are: application/vnd.ms-excel (Excel), text/xml (XML) and text/csv (CSV). If you choose XML mode, you may also pass an xslt parameter which names a stylesheet in the repository (full repository url required) which will be used to transform the XML while generating. In all cases, the resulting data will be streamed back to the client. The POST version should be used if sending more than about 4kB of parameters.

Service: GET /data/ElxirSamples/DataSource/FruitSales.ds
  • Parameter: any data source parameters (optional)
  • Parameter: mode

By entering "time" for the "mode" parameter, total number of records and elapsed time will be displayed.

Service: POST /data/ElixirSamples/DataSource/CustomerListing.ds
  • Parameter: datastore
  • Parameter: any data source parameters (optional)

Generate the data from the Composite DataSource into the named datastore. Note that this service is a POST, unlike the GET version above, because the server is modified by this operation - the data is written onto the server instead of being streamed back to the client. You will recall from the earlier discussion that POST operations may have side-effects - for example the datastore may append records to a JDBC database. You wouldn't want the same records appended twice! The GET version above is stateless, because the data is returned to the user - the server state doesn't change.

Glint

Service: GET /glint/ElixirSamples/Resources/sample.glint
  • Parameter: page (optional)
  • Parameter: mode (optional)

Returns the specified page of the glint, or the first page if no page parameter is supplied. If the mode value is "page-count" then a plain text number is returned indicating the number of pages available.

Job

Service: POST /job/ElixirSamples/Job/JobSample.job
  • Parameter: any job parameters (optional)

Executes the job and returns the job log as a text stream.

Target

Service: POST /target/TargetName

Renders a report to the named target (TargetName). This service requires an XML structure to be sent as the request, detailing the specific report along with any rendering and target parameters that are required. You should always provide the mime-type target parameter unless the target is a PrintTarget. Other target parameters can be identified from the /query/targets service.

Request:

<request report="/ElixirSamples/Report/CustomerListing.rml">
  <report-parameters>
    <param name="paramName">value</param>
  </report-parameters>
  <render-details> <!-- optional -->
  </render-details>
  <target-parameters>
    <param name="mime-type">application/pdf</param>
  </target-parameters>
</request>

Log

Service: GET /log/file/activity.log

(Admin only)

Returns the contents of any log file from the server /log directory. Substitute activity.log for any other log name to have it streamed back as plain text.

User

Service: GET /user

(Admin only)

Lists all users and their groups

Response:

<users>
  <user id="1" name="admin" enabled="yes">
    <group id="1" name="admin"/>
  </user>
  <user id="2" name="scheduler" enabled="yes">
    <group id="3" name="scheduler"/>
  </user>
  <user id="3" name="user" enabled="yes">
  </user>
</users>
Service: GET /user/bill

(Admin only)

Lists a named user and their groups

Response:

<user id="1" name="admin" enabled="yes">
 <group id="1" name="admin"/>
</user>
Service: PUT /user/bill

(Admin only)

Adds or edits user bill. When creating, don't specify the name attribute, because it is part of the URL. The enabled state defaults to true if not specified. You can specify a name while editing to rename the user. When editing, leaving out the name, password or enabled attributes indicates that those values are unchanged. Similarly, leaving out the group children indicates that the groups remain unchanged. If you want to remove all groups, you should specify a single child group with no id (this overrides the no groups means no change inference).

Request:

<user name="bill" password="XXX" enabled="yes">
  <group id="1">
  <group id="2">
</user>
Service: DELETE /user/bill

(Admin only)

Deletes the named user

Group

Service: GET /group

(Admin only)

Lists all groups and their users

Response:

<groups>
  <group id="2" name="*"/>
  <group id="1" name="admin">
  	<user id="1" name="admin"/>
  </group>
  <group id="3" name="scheduler">
  	<user id="2" name="scheduler"/>
  </group>
</groups>
Service: GET /group/scheduler

(Admin only)

Lists the group called scheduler and its users

Response:

<group id="3" name="scheduler">
  <user id="2" name="scheduler"/>
</group>
Service: PUT /group/testing

(Admin only)

Adds or edits the group called testing. When creating, don't specify the name attribute as it is part of the URL. You can specify a name while editing to rename the group. Leaving out the user children indicates that the users remain unchanged. If you want to remove all users from the group, you should specify a single child user with no id (this overrides the no users means no change inference).

Request:

<group name="testing">
 <user id="1">
 <user id="2">
</group>
Service: DELETE /group/testing

(Admin only)

Deletes the named group