20.0.0 Report Engine for RESTful API Reference

The Reporting Engine for RESTful (the Engine) API is used to provide embedding applications the ability to interact with the Engine server installed at your site. The API provides the means to send JSON or XML requests to the Engine, e.g. a report template and URL to a data source; and to receive JSON or XML responses from the Engine, e.g. output generated from a report template.

We also provide example Engine HTTP client applications for a variety of programming languages.

Changes in Version 20.0.0

  • Functionality was added to inject a license key into the RESTful Engine.
  • An API endpoint was added to get tag information from a template

Engine Request Headers

This article shows request and response bodies using the XML format. However, JSON can be used instead. For JSON, all that is required is to provide the corresponding Content-Type and Accept headers while sending requests to the Engine. For example, if you send a request to the 'v1/version' resource (as shown below), and you would like to receive the response as a JSON string, add Accept: application/json to the request's header.

XML and JSON request headers 

  • Send an XML request to the Engine: Content-Type: application/xml
  • Receive an XML response from the Engine: Accept: application/xml
  • Send a JSON request to the Engine: Content-Type: application/json
  • Receive a JSON response from the Engine: Accept: application/json 

Reporting Engine for RESTful API

Some APIs require a request body be sent to the resource as well as an HTTP verb. Those are specified below.

Every API returns an HTTP response code to the requesting application. Many APIs also return an XML or JSON response body (such as a report template's output); both are also specified below.

Resource URLs

Resource Relative URL HTTP Verb
General v1/version GET
Reports v1/metrics POST
Reports v1/reports POST
Reports v1/reports/GUID GET
Reports v1/reports/GUID/status GET
Reports v1/reports/GUID DELETE
TagTree v1/tagtree POST

Resource Operations

If you send the Engine a POST request with the Async element set to true, you'll receive a response from the Engine with a generated output GUID. That GUID can be used in later requests to: fetch a template's output; query a template's output status; or delete a template's output.

Engine Errors

In general, if a request sent to the Engine resulted in an error, the Engine will return an HTTP status code like 404 (Not Found), and a response body with an error. For example, the Engine returns this error when the URI for a template in a POST request to the resource 'v1/reports' is incorrect:

<Error>
<Message>An error has occurred.</Message>
<ExceptionMessage>The remote server returned an error: (404) Not Found.</ExceptionMessage>
<ExceptionType>System.Net.WebException</ExceptionType>
<StackTrace>   at System.Net.WebClient.DownloadDataInternal(Uri address, WebRequest& request)
at System.Net.WebClient.DownloadData(Uri address)
at RESTfulEngine.BusinessLogic.d.a(Byte[] A_0, String A_1)
at RESTfulEngine.BusinessLogic.d.b(Template A_0)
at RESTfulEngine.Controllers.ReportsController.GenerateReport(Template template)
at RESTfulEngine.Controllers.ReportsController.ProcessTemplate(Template template)
at RESTfulEngine.Controllers.ReportsController.Post(Template template)</StackTrace>
</Error>
Click to copy

General Resource Operations

Relative URL v1/version
HTTP Verb GET
Description Get the version numbers of the Engine service and underlying Reporting Engine.
Response Code 200 (OK)
Request Body Required? No
Returns Response Body? Yes

Response Body Example

<Version>
<ServiceVersion>15.2.288.0</ServiceVersion>
<EngineVersion>15.2.288.0</EngineVersion>
<license>LICENCE KEY</license>
</Version>

Reports Resource Operations

Relative URL v1/metrics
HTTP Verb POST
Description Returns information stored in the template including data source, input parameters, file type and other information.
Response Code 200 (OK)
Request Body Required? No
Returns Response Body? Yes

Response Body Example

<Metrics xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<TemplateType>docx</TemplateType>
<Datasources>
<string>MANF_DATA_2009</string>
</Datasources>
<Tags>
<Tag>
<XmlType>12</XmlType>
<Text><wr:out select='/Root/Overhead/ForTheYearEnded' type='DATE' format='category:date;type:0;format:m/d/yyyy;' nickname='[Year Ending Date]' datasource='MANF_DATA_2009'/></Text>
<NodeName>Out</NodeName>
<HasNode>true</HasNode>
<Node>/Root/Overhead/ForTheYearEnded</Node>
[...]
</Metrics>
Relative URL v1/reports
HTTP Verb POST
Description Generate output from a report template. All desired output generation parameters should be coded within the request’s body.
Response Code 200 (OK)
Request Body Required? Yes
Returns Response Body? Yes

Request Body Example

This simple request body will return the template's output in a response body. It includes the URIs of the report template and data source; the data source nickname; the data source type; and the output format. Send this POST request with the Content-Type: application/xml header.

Note the URIs are only an example. They must be changed to reflect your RESTful Engine installation.

<Template>
    <Uri>http://windward.restfulengine.net:8080/SampleTemplates/Manufacturing.docx</Uri>
    <OutputFormat>pdf</OutputFormat>
    <Async>false</Async>
    <Datasources>
        <Datasource>
            <Name>MANF_DATA_2009</Name>
            <Type>xml</Type>
            <Uri>http://windward.restfulengine.net:8080/SampleTemplates/Manufacturing.xml</Uri>
        </Datasource>
    </Datasources>
</Template>

Response Body Example

The Engine delivers output from a report template as a Base64-encoded string within a response body (when the Async element is set to false). To receive an XML response body use the Accept: application/xml header in the POST request.

<Report xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
<Data>JVBERi0xLj[...]JUVPRgo=</Data>
</Report>
Relative URL v1/reports/GUID 
HTTP Verb GET
Description Retrieve output generated asynchronously. GUID was returned by a previous asynchronous POST request.
Response Code 200 (OK)
202 (Accepted) - if the output generation is still in progress
404 (Not Found) - if the requested output doesn't exist
Request Body Required? No
Response Body Returned? Yes - same as a POST to 'v1/reports' above.
Relative URL v1/reports/GUID 
HTTP Verb DELETE
Description Delete the previously asynchronously-generated output.
Response Code 200 (OK)
404 (Not found) – if the requested report does not exist
Request Body Required? No
Returns Response Body? No
Relative URL v1/reports/GUID/status
HTTP Verb GET
Description Get the status of asynchronously-generated output.
Response Code 200 (OK) – the output is ready
202 (Accepted) – the output generation is still in progress
404 (Not found) – the requested output does not exist
500 (Internal server error) – an error occurred during output generation
Request Body Required? No
Returns Response Body? No

TagTree Resource Operations

Relative URL v1/tagtree
HTTP Verb POST
Description Get the tag tree structure for the template document
Response Code 200 (OK)
Request Body Required? Yes
Returns Response Body? Yes

Response Body Example

<windward-tag-tree version="20.0.0.106">
    <ForEach nickname="[NICKNAME]" select="[SELECT]" var="[VAR]" datasource="[DATASOURCE]">
        <Out nickname="[NICKNAME]" select="[SELECT]" datasource="[DATASOURCE]" />
        <EndForEach nickname=":forEach]" />
    </ForEach>
</windward-tag-tree>

Request Body Elements

Here are the XML elements that can be included in an XML request body.

<Template>

    <!-- The source of the template - embedded or external. -->
    <!-- Embed template as a Base64-encoded string. -->
    <Data/> 
    <!-- The location of the external template. -->
    <Uri/> 

    <!-- Generate the report in the provided format. -->
    <OutputFormat>pdf|docx|xlsx|pptx|html|prn|csv|rtf|jpg|png|svg|eps|bmp|gif</OutputFormat> 

    <!-- If you are using printer output, use to specify main printer. Printer must be recognized by network -->
    <MainPrinter/>

    <!-- Set number of copies (integer) -->
    <PrintCopies/>

    <!-- Set first page printer if main printer is already set -->
    <FirstPagePrinter/>

    <!-- Assign print job name -->
    <PrinterJobName/>

    <!-- Generate the report asynchronously. The report can be queried or obtained later with additional requests. -->
    <Async>true|false</Async> 

    <!-- This is for Windward Scout installations only. Ignore if not Windward Scout. -->
    <ApiKey/> 

    <!-- Format of the template. Auto-determined if not provided. -->
    <Format>docx|xlsx|pptx</Format> 

    <!-- Data source description section. These elements will be applied in order. Note: Use SQL elements for SQL-only data sources. -->
    <Datasources>
        <Datasource>
            <!-- The nickname of the data source you specified in the Connection Editor in Report Designer. Use the value NoName if the data source name within the template is empty or absent. -->
            <Name/> 
    
            <!-- The data source type. -->
            <Type>sql|xml|xml2|json|odata|salesforce|salesforceoauth</Type> 

            <!-- For SQL data sources -->
            <ClassName>System.Data.SqlClient</ClassName>
        
            <!-- The connection string from the Connection Editor when you set up the data source in Report Designer. -->
            <ConnectionString/> 

            <!-- For XML, JSON, or OData data sources - embedded or external -->
            <Data/> <!-- Embed data source as a Base64-encoded string. -->
            <Uri/> <!-- The location of the external data source. --> 

            <!-- The user access token and soap endpoint for salesforceoauth -->
            <SalesforceAccessToken/>
            <SalesforceSoapEndpoint/>

            <!-- The user credentials for JSON and OData data sources (optional). -->            
            <Username/>
            <Password/>

            <!-- The domain name for JSON and OData data sources (optional). -->        
            <Domain/>
            <!-- The OData version. The Engine will use 1 if not provided. -->
            <ODataVersion>1|2|3|4</ODataVersion>
            <!-- The OData protocol. The Engine will use identity if not provided. -->
            <ODataProtocol>identity|basic|credentials|windowsauth</ODataProtocol>

            <!-- If an XSD file is used with your XML data source, use one of the following. -->
            <!-- Embed the XSD file as a Base64-encoded string. -->
            <SchemaData/>
            <!-- Location of external XSD file. -->             
            <SchemaUri/> 

            <!-- Variable section (must be within the <Datasources/> element). List of variables to use with the data source. -->
            <Variables>
                <Variable>
                    <!-- The name of the variable. -->
                    <Name/> 
                    <!-- The type of variable. The Engine will use text if not provided. -->
                    <Type>text|int|float|datetime</Type>
                    <!-- The variable's value. --> 
                    <Value/> 
                </Variable>
            </Variables>
        </Datasource>
    </Datasources>

    <!-- Settings section. These settings can be applied to the output being generated. Apply all that are needed. These settings correspond to members of the .NET Reporting Engine Report class. -->

    <!-- Template's version. Auto-determined if not provided. -->
    <Version/> 
    <CopyMetadata>never|nodatasource|always</CopyMetadata>
    <Description/>
    <!-- Name of the output file. -->
    <Title/> 
    <Subject/>
    <Keywords/>
    <Hyphenate>off|template|on</Hyphenate>
    <Locale/>
    <TrackImports/>
    <Timeout/>
    <RemoveUnusedFormats/>

    <!-- Inject the license key given. A license key specified in the request will be used instead of whatever license is specified in the engines config. --> 
    <License/>
</Template>


Example POST Request

Here's an example of an XML RESTful POST request body to output the Windward 'Manufacturing' sample. (Note the URIs are only an example. They must be changed to reflect your RESTful Engine installation.):

<Template>
    <Uri>http://windward.restfulengine.net:8080/SampleTemplates/Manufacturing.docx</Uri>
    <OutputFormat>pdf</OutputFormat>
    <Async>false</Async>
    <Datasources>
        <Datasource>
            <Name>MANF_DATA_2009</Name>
            <Type>xml</Type>
            <Uri>http://windward.restfulengine.net:8080/SampleTemplates/Manufacturing.xml</Uri>
        </Datasource>
    </Datasources>
    <CopyMetadata>always</CopyMetadata>
    <Description>PDF sample report</Description>
    <Title>testreport.pdf</Title>
    <Subject>Internet Marketing Report sample</Subject>
    <Keywords>none</Keywords>
    <Hyphenate>on</Hyphenate>
    <TrackImports>false</TrackImports>
    <Timeout>10</Timeout>
    <RemoveUnusedFormats>false</RemoveUnusedFormats>
    <License>sample string 25</License>
</Template>

Avoid any empty elements in your XML POST request body, e.g.  "<Title></Title>". Always provide a relevant value as in the example above.

POST Response Body Example

F.E: 
<string>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;windward-tag-tree version="20.0.0.86"&gt;
  &lt;ForEach nickname="[Employees]" select="/windward-studios/Employees" var="varName1" datasource="XML"&gt;
    &lt;Out nickname="[FirstName]" select="${varName1.Employee/FirstName}" datasource="XML" /&gt;
    &lt;Out nickname="[LastName]" select="${varName1.Employee/LastName}" datasource="XML" /&gt;
    &lt;EndForEach nickname="[:forEach]" /&gt;
  &lt;/ForEach&gt;
&lt;/windward-tag-tree&gt;</string>
Click to copy

Example Clients for the Engine

There are a variety of HTTP clients available you can use to interact with the Engine, including curl and Postman. We provide several example Engine HTTP clients in the Engine installation for different programming languages: