Working with File Resources

This chapter includes the following sections:

MIME Types
Downloading File Resources
Uploading File Resources
Updating File Resources

MIME Types

When downloading or uploading file contents, you must specify the MIME type (Multi-Purpose Internet Mail Extensions) that corresponds with the desired file type, as shown in the following table.

You can customize this list of MIME types in the server by editing the contentTypeMapping map in the file .../WEB-INF/applicationContext-rest-services.xml. You can change MIME types for predefined types, add MIME types, or add custom types.

MIME Types for File Contents

File Types

Corresponding MIME Types

pdf

application/pdf

html

text/html

xls

application/xls

rtf

application/rtf

csv

text/csv

ods

application/vnd.oasis.opendocument.spreadsheet

odt

application/vnd.oasis.opendocument.text

txt

text/plain

docx

application/vnd.openxmlformats-officedocument.wordprocessingml.
document

xlsx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

font

font/*

img

image/*

jrxml

application/jrxml

jar

application/zip

prop

application/properties

jrtx

application/jrtx

xml

application/xml

css

text/css

accessGrantSchema

application/accessGrantSchema

olapMondrianSchema

application/olapMondrianSchema

Downloading File Resources

There are two read operations on file resources:

Viewing the file resource details to determine the file format
Downloading the binary file contents

To view the file resource details, specify the URL and the file descriptor type as follows:

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/file/resource

Options

accept: application/repository.file+json

accept: application/repository.file+xml

Return Value on Success

Typical Return Values on Failure

200 OK – The response will contain the file resource descriptor.

404 Not Found – The specified resource is not found in the repository.

The type attribute of the file resource descriptor indicates the format of the contents. However, you can also download the binary file contents directly, with the format indicated by the MIME content-type of the response:

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/file/resource

Return Value on Success

Typical Return Values on Failure

200 OK – The response content-type will indicate the MIME type of the binary contents. See MIME Types for File Contents for the list of MIME types that correspond to file resource types.

 

404 Not Found – The specified resource is not found in the repository.

Uploading File Resources

There are several ways of uploading file contents to create file resources. The simplest way is to POST a file descriptor containing the file in base64 encoding.

Method

URL

POST

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/folder?<argument>

Argument

Type/Value

Description

create
Folders

true|false

True by default, and the service will create all parent folders if they don't already exist. When set to false, the folders specified in the URL must all exist, otherwise the service returns an error.

Content-Type

Content

application/repository.file+json

application/repository.file+xml

A well defined file resource descriptor, as described in File. The contents of the file are base64-encoded in the content attribute of the descriptor.

Return Value on Success

Typical Return Values on Failure

201 Created – The request was successful and, for confirmation, the response contains the full descriptor of the resource that was just created.

400 Bad Request – Mismatch between the content-type and the fields or syntax of the actual descriptor.

You can also create a file resource with a multipart form request. The request parameters contain information that becomes the name and description of the new file resource.

Method

URL

POST

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/folder

Content-Type

Content

multipart/form-data

The request should include the following parameters:

label – contains the name of the file resource
description – contains a description for the resource
type – contains a file type shown in MIME Types for File Contents
data – contains the file contents

Return Value on Success

Typical Return Values on Failure

201 Created – The request was successful and, for confirmation, the response contains the full descriptor of the resource that was just created.

400 Bad Request – Mismatch between the content-type and the fields or syntax of the actual descriptor.

Another form allows you to create a file resource by direct streaming, without needing to create it first as a descriptor object. In this case, the required fields of the file descriptor are specified in HTTP headers.

Method

URL

POST

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/folder

Options

Content-Description: <file-description> – Becomes the description field of the created file resource

Content-Disposition: attachment; filename=<filename> – Becomes the name of the file resource

Content-Type

Content

{MIME type}

The MIME type from MIME Types for File Contents that corresponds to the desired file type. The body of the request then contains the binary data representation of that file format.

Return Value on Success

Typical Return Values on Failure

201 Created – The request was successful and, for confirmation, the response contains the full descriptor of the resource that was just created.

400 Bad Request – Mismatch between the content-type and the fields or syntax of the actual descriptor.

Updating File Resources

For an existing file resource, you can update its name, description or file contents in several ways.

The simplest way is to PUT a file descriptor containing the new file in base64 encoding. This new definition of the file resource overwrites the previous one.

Method

URL

PUT

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/resource

Content-Type

Content

application/repository.file+json

application/repository.file+xml

A well defined file resource descriptor, as described in File. The new contents of the file are base64-encoded in the content attribute of the descriptor.

Return Value on Success

Typical Return Values on Failure

201 Created – The request was successful and, for confirmation, the response contains the full descriptor of the resource that was just created.

400 Bad Request – Mismatch between the content-type and the fields or syntax of the actual descriptor.

The second method allows you to update a file resource by direct streaming. You can specify the Content-Description and Content-Disposition headers to update the resource description or name, respectively.

Method

URL

PUT

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources/path/to/resource

Options

Content-Description: <file-description> – Becomes the description field of the created file resource

Content-Disposition: attachment; filename=<filename> – Becomes the name of the file resource

Content-Type

Content

{MIME type}

The MIME type from MIME Types for File Contents that corresponds to the desired file type. The body of the request then contains the binary data representation of that file format.

Return Value on Success

Typical Return Values on Failure

201 Created – The request was successful and, for confirmation, the response contains the full descriptor of the resource that was just created.

400 Bad Request – Mismatch between the content-type and the fields or syntax of the actual descriptor.

 

Version: 
Feedback