GET Export SQL

Abstract

The GET Export SQL endpoint returns the SQL to be sent to the database if the GET Export Report API were requested with identical parameters.


Overview

The GET Export SQL endpoint returns the SQL to be sent to the database if the GET Export Report API were requested with identical parameters. This endpoint is useful for administrators desiring visibility into Pull Reports™ SQL queries.

Because this endpoint may aid attackers hoping to mount SQL based attacks against the <report> data structure, the GET Export SQL endpoint is disabled by default. Activate the endpoint via the export.sql.active configuration property after appropriately securing the endpoint to permitted users.

Securing the GET Export SQL

Since the GET Export SQL endpoint is prefixed with the /pullreports/admin directory path, it is easy to secure all requests to the endpoint with the /pullreports/admin/* URL pattern. For instance, assuming Servlet Container based security, the following <security-constraint> in the Pull Reports™ installation WAR's web.xml restricts access to users with the ADMINISTRATOR role.

<security-constraint>
    <display-name>User</display-name>
       <web-resource-collection>
            <web-resource-name>PullReports Administration</web-resource-name>
            <url-pattern>/pullreports/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>ADMINISTRATOR</role-name>
    </auth-constraint>
</security-constraint>
<security-role>
    <role-name>ADMINISTRATOR</role-name>
</security-role>
 

URL

/[context]/pullreports/admin/catalog/[catalog id]/report/[report id]/export/sql(.json)

URL Components
/[context]

The web application context path of the WAR which contains the Pull Reports™ JAR. Typically this is the name of the WAR file.

/pullreports

The URL path to the PullReportsServlet. This path is configured automatically web.xml when installing Pull Reports™.

/admin

Defines the administrative directory space.

/catalog/[catalog id]

The id of the <catalog> as configured in Pull Reports™ XML Catalog files.

/report/[report id]

The id of the <report> as configured in the encompassing <catalog>.

/export/sql

The export SQL endpoint.

(.json)

Optionally appending .json to the URL or setting the HTTP Accept header to application/json returns the JSON format response.

Parameters

format, columns, distinct, filter, limit, offset, sort

These seven parameters have the same structural definition as the corresponding parameters in the GET Export Report endpoint.

What does the format parameter do?

Since the Export SQL varies slightly by GET Export Report format parameter value, use this parameter to view the SQL per format. If not specified, the default value is json.

Response

OK

Status Code:  200

HTML Format

Response Content-Type:  text/html

The html format writes a complete HTML document to the HTTP response body. The query SQL is written within the HTML document. This response is the default response unless .json is appended to the URL or the endpoint is requested with the application/json Accept header.

JSON Format

Response Content-Type:  application/json

The json format writes JSON to the HTTP response body containing both the query SQL and query parameters if applicable.

The JSON response is returned if .json is appended to the URL or the endpoint is requested with the application/json Accept header.

JSON responses without error have this structure:

{
    "query":{
        "sql":string
        // The parameters property is an array of values to be substituted
        // at the respective positions of "?" characters in the Prepared
        // JDBC query. 
        ,"parameters":[object]
    }
}
Example 1. Example JSON Output Format
{
    "query": {
        "sql": "select t1.id, t1.name from table_name t1 where 1=1 and t1.last_updated > ?"
        ,"parameters":["2015-09-29T00:00:00.000Z"]
    }
}

Bad Request

Status Code: 400

Responses whose columns parameter results in zero exportable, permitted columns return a 400 response.

Forbidden

Status Code: 403

A 403 status code is returned if an <access_control_voter> associated with the <report> or <catalog> fails. A 403 status is also returned if an <access_control_voter> associated with a <relationship> or <column> referenced via the columns, filter, or sort parameter fails.

Internal Server Error

Status Code:  500

HTTP responses with error return a 500 status code, have an empty HTTP response body, and log information about the error to the com.pullreports.ADMIN logger.