Skip to main content
Windward

RESTful Engine API

Overview 

The RESTful Engine API (application program interface) is used to interact with the RESTful Engine server installed in your network environment. If you would prefer to use one of the RESTful clients, please see:

 

 

 

This documentation 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 making requests to the RESTful Engine. For example, if you are making a 'v1/version' request (as shown below) and you would like to receive the response as a JSON string, add 'Accept: application/json' to the request's header.

 

Once the RESTful Engine receives your POST request, you will receive a response from the Engine with the generated report GUID.

 

RESTful Engine API

Summary

Resource

Relative URL

HTTP Verb

General

 

 

 

v1/version

GET

Reports

 

 

  v1/metrics POST

 

v1/reports

POST

 

v1/reports/{guid}

GET

 

v1/reports/{guid}/status

GET

 

v1/reports/{guid}

DELETE

General

Operation

v1/version

HTTP Verb

GET

Description

Get the version numbers associated with the RESTfulEngine service and underlying reporting engine.

Request body example

N/A

Response code

200 (OK)

Return response example

<Version>

<ServiceVersion>1.0.0.0</ServiceVersion>

<EngineVersion>1.0.0.0</EngineVersion>

</Version>

Reports

 

Operation v1/metrics
HTTP Verb POST
Description Returns information stored in the template including data source, input parameters, file type and other information.
Request body The same as POST. Only the data field will be used.

Response code

200 (OK)

Return value Information about data sources and input parameters used in the template.

Response code

200 (OK) – if asynchronous operation requested

Return response example

<Error>

<ErrorMessage/>

</Error>

 


 

Operation

v1/reports

HTTP Verb

POST

Description

Generate a report. All desired report generation parameters should be supplied via the request’s body.

Request body example (XML)

<Template>

(The source of the template.)

 

<Data/>

(Embed template as Base64 encoded data.)

 

<Uri/>

(The location from where to get the template.)

 

<OutputFormat>pdf|docx|xlsx|pptx|html|csv|rtf</OutputFormat>

(Generate the report in the provided format.)

 

<Async>true|false</Async>

(Generate the report asynchronously. The report can be queried/obtained later with additional requests.)

 

<ApiKey/>

(This is for Windward Scout installations only. Ignore if not Windward Scout. )

 

<EngineVersion/>

(Version of the RESTful Engine to use. This version must be available on the server. If absent, the latest available version is used.) (currently not implemented)

 

    <Format>docx|xlsx|pptx</Format>

(Format of the template. Auto-determined if not provided.)

 

 

Data source description section. These will apply in order. Note: Use SQL nodes for SQL only data sources.

 

<Datasources>

<Datasource>

 

<Name/>

(The Name of the Data Source that you set up in the Connection Editor in AutoTag. Use the value 'NoName' if the data source name within the template is empty or absent.)

 

<Type>sql|xml|json|odata</Type>

(The type of the data source.)

 

For SQL data sources.

<ClassName>System.Data.SqlClient</ClassName>

<ConnectionString/>

 

For XML, JSON, or OData data sources.

(Accept an external or embedded resource. If embedding data, use Base64 encoded data using the <Data/> node.)

<Data/>

<Uri/>

 

<Username/>
<Password/>

(The user credentials to be used with JSON and OData data sources. [Optional])

 

<Domain/>

(The domain name to be used with JSON and OData data sources. [Optional])

 

<ODataVersion>1|2|3|4</ODataVersion>

(An OData version. The service will use '1' if not provided.)

 

<ODataProtocol>identity|basic|credentials|windowsauth</ODataProtocol>

(An OData protocol. The service will use 'identity' if not provided.)

 

(If an .XSD is used with your XML data source, use one of the following. Use Base64 for <SchemaData>)

<SchemaData/>

<SchemaUri/>

 

 

 

Variable section (within the Datasources section). List of variables to use with the data source.

<Variables>

<Variable>

 

<Name/>

(The variable name.)

 

<Value/><Type>text|int|float|datetime</Type>

(The type of variable. The service will use 'text' if not provided.)

 

</Variable>

</Variables>

 

</Datasource>

</Datasources>

 

Settings section. These settings can be applied to the report being generated. Apply all that are needed. These correspond to the settings available in the Report* class.

 

<Version/>

(Template's version. This will be Auto-determined if not provided.)

 

<CopyMetadata>never|nodatasource|always</CopyMetadata>

 

<Description/>

 

<Title/>

(Name you want to give the output file.)

 

<Subject/>

 

<Keywords/>

 

<Hyphenate>off|template|on</Hyphenate>

 

<Locale/>

 

<TrackImports/>

 

<Timeout/>

 

<RemoveUnusedFormats/>

 

</Template>

 

Response code

200 (OK)

Return response example

<Report>

<Data>base64 encoded report file</Data>

</Report>

Response code

200 (OK) – if asynchronous operation requested

Return response example

<Error>

<ErrorMessage/>

</Error>

 


 

Operation

v1/reports/{guid}

HTTP Verb

GET

Description

Retrieve a previously generated report or query the status of an asynchronous report generation.

Request body example

N/A

Response code

200 (OK)

Return response example

<Report>

<Data>base64 encoded report file</Data>

</Report>

Response code

202 (Accepted) – if the report generation is still in progress

Response code

404 (Not found) – if the requested report does not exist

 


 

Operation

v1/reports/{guid}/status

HTTP Verb

GET

Description

Retrieve a status of a report sent for the asynchronous generation.

Request body example

N/A

Response code

200 (OK) – the report is ready.

Response code

202 (Accepted) – if the report generation is still in progress.

Response code

404 (Not found) – if the requested report does not exist.

Response code

500 (Internal server error) – if error during report generation.

 


 

Operation

v1/reports/{guid}

HTTP Verb

DELETE

Description

Delete the previously generated report.

Request body example

N/A

Response code

200 (OK) – the operation was successful.

Response code

404 (Not found) – if the requested report does not exist.

 

 

Sample RESTful POST Request

The simple structure of your RESTful call can look like like these:

Referencing Filepaths.

Insert the UIR, Data Source Nickame, Type, and other info or credentials for accessing your data source.

Using BLOBs for your Datasource.

Convert your entire datasource into a BLOB and insert it in the Data node

<Template>
   <Uri></Uri>
   <OutputFormat></OutputFormat>
   <Async></Async>
   <Datasources>
       <Datasource>
            <Name></Name>
            <Type></Type> *this is your data source type
            <other-DS-Info></other-DS-Info>

            <other-DS-Info></other-DS-Info>

            <other-DS-Info></other-DS-Info>

            <other-DS-Info></other-DS-Info>

            <Variable>

                <Variables></Variables>

            </Variable>
        </Datasource>
    </Datasources>
   <OtherSettings></OtherSettings>

   <OtherSettings></OtherSettings>   

   <OtherSettings></OtherSettings>
</Template>

<Template>
   <Data></Data>
   <OutputFormat></OutputFormat>
   <Async></Async>
  
<Other Settings></OtherSettings>

   <Other Settings></OtherSettings>   

   <Other Settings></OtherSettings>
</Template>

 

 

 

This is an example of how to form your XML RESTful POST request to output the Windward 'Internet Marketing Report' sample:

 

<Template>
    <Uri>
http://windward.restfulengine.net:8080/Samples/InternetMarketingReport.docx</Uri>
    <OutputFormat>pdf</OutputFormat>
    <Async>false</Async>
    <Datasources>
        <Datasource>
            <Name>INTMARKETING</Name> <!--datasource name used when creating the template in AutoTag-->
            <Type>xml</Type> <!--type of datasource you are using-->
            <Uri>
http://windward.restfulengine.net:8080/Samples/InternetMarketingReport.xml</Uri>
        </Datasource>
    </Datasources>
    <CopyMetadata>always</CopyMetadata>
    <Description>PDF sample report</Description>
    <Title>testreport.pdf</Title> <!--name you want to give the output file-->
    <Subject>Internet Marketing Report sample</Subject>
    <Keywords>none</Keywords>
    <Hyphenate>on</Hyphenate>
    <TrackImports>false</TrackImports>
    <Timeout>10</Timeout>
    <RemoveUnusedFormats>false</RemoveUnusedFormats>
</Template>

 

You will not want to leave any nodes that you provide in your POST XML call empty (i.e. <Title></Title>). Please provide a relevant value like you see in the example above.

 

 

Once the RESTful Engine receives your POST request, you will receive a response from the Engine with the generated report GUID.