21.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.

New in version 21.0.0

  • There is now a new endpoint that allows you to get the generated report back as a stream either through your browser (to download it) or through code. The new endpoint is "/v2/document/{GUID}/file. This allows you to retrieve much larger generated reports. Read more about it in this section Reports Resource Operations

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 v2/version GET
Metrics v2/metrics POST
Metrics v2/metrics/GUID GET
Metrics v2/metrics/GUID/status GET
Metrics v2/Metrics/GUID DELETE
Document v2/document POST
Document v2/document/GUID GET
Document  v2/document/GUID/status GET
Document v2/document/GUID DELETE
Document v2/document/GUID/file
GET
TagTree v2/tagtree POST
TagTree v2/tagtree/GUID
GET
TagTree
v2/tagtree/GUID/status
GET
TagTree
v2/tagtree/GUID
DELETE

Resource Operations

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>

General Resource Operations

Relative URL v2/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

<VersionInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<ServerApiVersion>2.0.0.0</ServerApiVersion>

<ServiceVersion>21.0.0.37</ServiceVersion>

<EngineVersion>21.0.0.37</EngineVersion>

</VersionInfo>

Documents Resource Operations

Relative URL v2/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 v2/document
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. To receive an XML response body use the Accept: application/xml (JSON Accept: application/json ) header in the POST request. All responses will have a populated URI entry. If the generated report is smaller than 30MB, then the Data entry in the response will be populated with the Base64-encoded string mentioned above. If the generated report is larger than 30MB, then the Data entry will be set to null, and you can get the generated report as a stream through your browser (for downloading) or through code by hitting the new endpoint: 

/v2/document/{GUID}/file

<Document>
<Guid></Guid>
<Data>JVBERi0xLj[...]JUVPRgo=</Data>
<Uri>http..../v2/document/{GUID}/file</Uri>
<Pages></Pages>
<NumOfPages></NumOfPages>
<Tag></Tag>
<ImportInfo></ImportInfo>
<Errors></Erros>
</Document>
Relative URL v2/document/GUID 
HTTP Verb GET
Description Retrieve output generated. GUID was returned by a previous 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 'v2/document' above.
Relative URL v2/document/GUID /file
HTTP Verb GET
Description Retrieve output generated as a file stream through browser, or code (not Postman)
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? No
Relative URL v2/document/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 v2/document/GUID/status
HTTP Verb GET
Description Get the status of asynchronously-generated output.
Response Code 201 (Created) – the output generation request has been accepted
202 (Accepted) – the output generation is still in progress
302 (Ready) - Output is ready
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 v2/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
Relative URL v2/tagtree/GUID 
HTTP Verb GET
Description Retrieve tagtree generated. 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
Relative URL v2/tagtree/GUID/status
HTTP Verb GET
Description Retrieve output generated. 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? No
Relative URL v2/tagtree/GUID 
HTTP Verb DELETE
Description Delete tagtree generated. GUID was returned by a previous asynchronous POST request.
Response Code 200 (OK)
404 (Not found) – if the requested report does not exist
Request Body Required? No
Response Body Returned? Yes - same as a POST to 'v1/reports' above.

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>

Config Settings

These are some config settings you should adjust if you are processing larger templates and getting errors in doing so.

<httpRuntime maxRequestLength="4096"  executionTimeout="180"/>

maxRequestLength The maximum request size in kilobytes. The default size is 4096 KB (4 MB). So if you are including the actual encoded template in your request body (and its a large template), you might want to change this value (more info).


executionTime (in seconds) is the time before a request times out. For larger templates, posting the document may take longer than usual, so if you are seeing that the engine is timing out on posting the template, change this value (more info).

<requestLimits maxAllowedContentLength="30000000" />

maxAllowedContentLength specifies the maximum length of content in a request, in bytes.

The default value is 30000000, which is approximately 28.6MB (more info). 

Documentation for Windward RESTFul API

SwaggerHub

SwaggerHub is a collaborative platform where you can define your APIs using the OpenAPI Specification. You can find the documentation on how to embed the Windward RESTFul API in your project on Swagger. Here you will find all the information you need on the methods used to communicate with the RESTful engine as well as the methods used to send requests.


ASP.NET Web Documentation

You can also access the ASP.NET web documentation by hitting the /help endpoint for your engine  (ex. localhost/help), where you will find documentation on all our methods for using the RESTful API.

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, check out this article.

We also have a Nuget package that allows you to use .Net Core or Framework to run the RESTful engine, as well as a Maven package that allows you to use Java to run the RESTful Engine.