The resources Service

The rest_v2/resources service searches the repository and access the resources it contains. This service provides performance and consistent handling of resource descriptors for all repository resource types. The service has two formats, one takes search parameters to find resources, the other takes a repository URI to access resource descriptors and file contents.

For further information, see:

Working With Resources for general guidelines about using descriptors.
Resource Descriptors for a reference to every type of resource and its attributes.
Working With File Resources to download and upload file resources.
Working With Domains to view Domains and their nested resources.

This chapter includes the following sections:

Searching the Repository
Paginating Search Results
Viewing Resource Details
Creating a Resource
Modifying a Resource
Copying a Resource
Moving a Resource
Deleting Resources

Searching the Repository

The resources service, when used without specifying any repository URI, is used to search the repository. The various parameters listed in the following table let you refine the search and specify how you receive search results. For example, the search and results pagination parameters can be used to implement an interface to repository resources in a REST client application.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources?<arguments>

Argument

Type/Value

Description

q

String

Search for resources having the specified text in the name or description. Note that the search string does not match in the ID of resources.

folderUri

String

The path of the base folder for the search.

recursive

true|false

Indicates whether search should include all sub-folders recursively. When omitted, the default behavior is recursive (true).

type

String

Match only resources of the given type. Valid types are listed in Resource Descriptors, for example: dataType, jdbcDataSource, reportUnit, or file. Multiple type parameters are allowed. Wrong values are ignored.

accessType

viewed
|modified

Filters the results by access events: viewed (by current user) or modified (by current user). By default, no access event filter is applied.

dependsOn /path/to/resource Searches for all resources depending on specified resource. Only data source and reportUnit resources may be specified. If this parameter is specified, then all the other parameters except pagination are ignored.

showHidden
Items

true|false

When set to true, results include nested local resources (in _files) as if they were in the repository. For more information, see Local Resources. By default, hidden items are not shown (false).

sortBy

optional
String

One of the following strings representing a field in the results to sort by: uri, label, description, type, creationDate, updateDate, accessTime, or popularity (based on access events). By default, results are sorted alphabetically by label.

limit
offset
forceFullPage
forceTotalCount

Pagination is enabled by default, and the default limit is 100 results. If you work with large repositories, you may not receive all results in a single request, and you must handle pagination issues. These parameters are described in Paginating Search Results.

Note that the pagination limit is applied to raw search results before permissions are computed. After permissions, the result set may be less than 100. In extreme cases, the search may return only a few items, but the search is still incomplete. In that case use forceFullPage as described in Full Page Pagination, or set the limit to 0 as described in No Pagination.

Options

accept: application/json (default)

accept: application/xml

Return Value on Success

Typical Return Values on Failure

200 OK – The body contains a list of resourceLookup descriptors representing the results of the search.

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

204 No Content – All type values specified are invalid.

The response of a search is a set of shortened descriptors showing only the common attributes of each resource. One additional attribute specifies the type of the resource. This allows the client to quickly receive a list of resources for display or further processing.

application/json

application/xml

[
    {
        "uri" :"/sample/resource/uri", 
        "label":"Sample Label", 
        "description":
            "Sample Description",
        "type":"folder" 
        "permissionMask":"0",
        "creationDate":
            "2013-07-04T12:18:47",
        "updateDate":
            "2013-07-04T12:18:47", 
        "version":"0"
    },
    ...
]
<resources>
    <resourceLookup>
        <uri>/sample/resource/uri</uri>
        <label>Sample Label</label>
        <description>Sample Description
            </description>
        <type>folder</type>
        <permissionMask>0</permissionMask>
        <creationDate>2013-07-04T12:18:47
            </creationDate>
        <updateDate>2013-07-04T12:18:47
            </updateDate>
        <version>0</version>
    </resourceLookup>
    ...
</resources>

Paginating Search Results

Paginating search results can speed up the user experience by making smaller queries and displaying the fewer results one page at a time. By default, a page is approximately 100 repository items. If and when users request another page, your application needs to send another request to the server with the same search parameters but an updated offset number that fetches the next page.

When any folder in your repository contains more than 100 subfolders and resources, then the search results will be paginated by default. This means you will not receive all results in a single request. In this case, you must use the pagination parameters to obtain more pages or change the pagination strategy as explained below.

Your application could perform further optimizations such as requesting a page and storing it before the user requests it. That way, the results can be displayed immediately, and each page can be fetched in the background while the user is looking at the previous page.

Pagination is complicated by the fact that JasperReports Server enforces permissions after performing the query based on your search parameters. This means that a default search can return fewer results than a full page, but this behavior can be configured.

There are 3 different combinations of settings that you can use for pagination.

Default pagination - Every page may have less than a complete page of results, but this is the fastest strategy and the easiest to implement.
Full page pagination - Ensures that every page has exactly the number of results that you specify, but this makes the server perform more queries, and it requires extra logic in the client.
No pagination - Requests all search results in a single reply, which is simplest to process but can block the caller for a noticeable delay when there are many results.

The advantages and disadvantages of each pagination strategy are described in the following sections. Choose a strategy for your repository searches based on the types searches being performed, the user performing the search, and the contents of your repository. Every request to the resources service can use a different pagination strategy; it's up to your client app to use the appropriate strategy and process the results accordingly.

Default Pagination

With the default pagination, every page of results returned by the server may contain less than the designated page size. You can determine the number of actual results from the HTTP headers of the response. The headers also indicate whether there are further pages to fetch.

Default pagination has the best performance and, when configured with the right limit for the size of your repository, almost no delay in response for your users. Because results are filtered by permissions, the user credentials that you specify for the request determine how full each page is:

The system admin (superuser) has access to every resource, and therefore the results are effectively unfiltered and each page is full. But the same can be true when you perform a search as jasperadmin within his organization, or even as a plain user within a folder where the user has full read permission. In these cases the default pagination is very efficient and has no partially-full pages.
If you are performing a sparse search, for example finding all reports that a given user has permission to access within an entire and large organization, then the results may have many partially-full page, all of differing lengths. In this case, you may prefer to use Full Page Pagination.

Arguments to resources for Default Pagination

Argument

Type/Value

Description

limit

integer
default is 100

This defines the page size, which is maximum number of resources to return in each response. However, with default pagination, the response is likely have less than this value of responses. The default limit is 100. You can set the limit higher or lower if you want to process generally larger or smaller pages, respectively.

offset

integer

By setting the offset to a whole multiple of the limit, you select a specific page of the results. The default offset is 0 (first page). With a limit of 100, subsequent calls should set offset=100 (second page), offset=200 (third page), etc.

forceFullPage false (default) The default is false, so you do not need to specify this parameter.

forceTotal
Count

true|false

When true, the Total-Count header is set in every paginated response, which impacts performance. When false, the default, the header is set in the first page only. Note that Total-Count is the intermediate, unfiltered count of results, not the number of results returned by this service.

With each response, you can process the HTTP headers to help you display pagination controls:

Headers in Responses for Default Pagination

Header Description
Result-Count This is the number of results that are contained in the current response. It can be less than or equal to the limit.
Start-Index The Start-Index in the response is equal to the offset specified in the request. With a limit=100, it will be 0 on the first page, 100 on the second page, etc.
Next-Offset This is the offset to request the next page. With forceFullPage=false, the Next-Offset is equivalent to Start-Index+limit, except on the last page. On the last page, the Next-Offset is omitted to indicate there are no further pages.
Total-Count

This is the total number of results before permissions are applied. This is not the total number of results for this search by this user, but it is an upper bound. Dividing this number by the limit gives the number of pages that will be required, though not every page will have the full number of results.

As described in the previous table, this header only appears on the first response, unless forceTotalCount=true.

Full Page Pagination

Full Page pagination ensures that every page, except the last one, has the same number of results, the number given by the limit parameter. To do this, JasperReports Server performs extra queries after filtering results for permission, until each page has the full number of results. Though small, the extra queries have a performance impact and may slow down the request. In addition, your client must read the HTTP header in every response to determine the offset value for the next page.

For full page pagination, set the pagination parameters of the resources service as follows:

Arguments of resources for Full Page Pagination

Argument

Type/Value

Description

limit

integer
default is 100

Specifies the exact number of resources to return in each response. This is equivalent to the number of results per page. The default limit is 100. You can set the limit higher or lower if you want to process larger or smaller pages, respectively.

offset

integer

Specifies the overall offset to use for retrieving the next page of results. The default offset is 0 (first page). For subsequent pages, you must specify the value given by the Next-Offset header, as described in the next table.

forceFullPage true Setting this parameter to true enables full page pagination. Depending on the type of search and user permissions, this parameter can cause significant performance delays.

forceTotal
Count

do not use

When forceFullPage is true, the Total-Count header is set in every response, even if this parameter is false by default.

With each response, you must process the HTTP headers as follows:

Headers in Responses for Full Page Pagination

Header Description
Result-Count This is the number of results that are contained in the current response. With full page pagination, it is equal to the limit in every response except for the last page.
Start-Index The Start-Index in the response is equal to the offset specified in the request. It changes with every request-response.
Next-Offset The server calculates this value based on the extra queries it performed to fill the page with permission-filtered results. In order to avoid duplicate results or skipped results, your client must read this number and submit it as the offset in the request for the next page. When this value is omitted from the header, it indicates there are no further pages.
Total-Count This is the total number of results before permissions are applied. This is not the total number of results for this search by this user, but it is an upper bound.

No Pagination

In certain cases, you can turn off pagination. Use this for small search request that you want to process as a whole, for example a listing of all reports in a folder. In this case, you receive and process all results in a single response and do not need to implement the logic for pagination. You should only use this for result sets that are known to be small.

To turn off pagination, set the pagination parameters of the resources service as follows:

Arguments to resources for No Pagination

Argument

Type/Value

Description

limit

0

To return all results without pagination, set limit=0. Do not set limit=0 for large searches, for example from the root of the repository, because it can cause significant delays and return a very large number of results.

offset

do not use

The default offset is 0, which is the start of the single page of results.

forceFullPage do not use This setting has no meaning when there is no limit.

forceTotal
Count

do not use

The Total-Count header is included in the first (and only) response. Note that Total-Count is the intermediate, unfiltered count of results, not the number of results returned by this service.

With each response, you must process the HTTP headers as follows:

Headers in Responses for No Pagination

Header Description
Result-Count This is the number of results contained in the current response. Thus, this header indicates how many results you should process in the single response.
Start-Index This is 0 for a single response containing all the search results.
Next-Offset This header is omitted because there is no next page.
Total-Count This is the total number of results before permissions are applied. It is of little use.

Viewing Resource Details

Use the GET method and a resource URI to request the resource's complete descriptor.

Method

URL

GET

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

Argument

Type/Value

Description

expanded

true|false

When true, all nested resources will be given as full descriptors. The default behavior, false, has all nested resources given as references. For more information, see Local Resources.

Options

accept: application/json (default)

accept: application/xml

accept: application/repository.folder+<format> (specifically to view the folder resource)

Return Value on Success

Typical Return Values on Failure

200 OK – The response will indicate the content-type and contain the corresponding descriptor, for example:

application/repository.dataType+json

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

Creating a Resource

The POST and PUT methods offer alternative ways to create resources. Both take a resource descriptor but each handles the URL differently.

With the POST method, specify a folder in the URL, and the new resource ID is created automatically from the label attribute in its descriptor.

Method

URL

POST

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

Argument

Type/Value

Description

create
Folders

true|false

By default, this is true, 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.
<resourceType>+json

application/repository.
<resourceType>+xml

A well defined descriptor of the specified type and format. See Resource Descriptors

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.

With the PUT method, specify a unique new resource ID as part of the URL. For more information, see Resource URI.

Method

URL

PUT

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

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.

overwrite

true|false

When true, the resource given in the URL is overwritten even if it is a different type than the resource descriptor in the content. The default is false.

Content-Type

Content

application/repository.
<resourceType>+json

application/repository.
<resourceType>+xml

A well defined descriptor of the specified type and format. See Resource Descriptors

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 POST method also supports a way to create complex resources and their nested resources in a single multipart request.

Method

URL

POST

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

Content-Type

Content

multipart/form-data

Root resource multipart item name: resource

Root resource multipart Content-type and corresponding item names:

mondrianConnection
schema – Mondrian schema XML file
secureMondrianConnection
schema – Mondrian schema XML file
accessGrantSchemas.accessGrantSchema[{itemIndex}] – XML file
semanticLayerDataSource
schema – Domain schema XML file
securityFile – XML security file
bundles.bundle[{bundleIndex}] – Properties file for internationalization
reportUnit
jrxml – Report unit JRXML file
files.{fileName} – Report unit attached resource file (e.g. images)

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.

Modifying a Resource

Use the PUT method to overwrite an entire resource.

The PUT method sends the entire descriptor for the resource. Specify the path of the target resource in the URL, and specify a resource of the same type in the descriptor. If you want to replace a resource of a different type, specify the overwrite=true argument. The createFolders argument isn't used for updates because the resource and the folders in its path must exist already.

The resource descriptor must completely describe the updated resource, not use individual fields. The descriptor must also use only references for nested resources, not other resources expanded inline. To update a local resource, use the PUT method with the hidden folder _file in the path, and send a complete descriptor for the updated resource. For more information, see Local Resources.

Method

URL

PUT

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

Argument

Type/Value

Description

overwrite

true|false

When true, the resource given in the URL is overwritten even if it is a different type than the resource descriptor in the content. The default is false.

Content-Type

Content

application/repository.
<resourceType>+json

application/repository.
<resourceType>+xml

A well defined descriptor of the specified type and format. See Resource Descriptors.

Return Value on Success

Typical Return Values on Failure

201 Created – The resource was replaced and the response contains the full descriptor of the updated resource.

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

Copying a Resource

Copying a resource uses the Content-Location HTTP header to specify the source of the copy operation. If any resource descriptor is sent in the request, it is ignored.

Method

URL

POST

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

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.

overwrite

true|false

When true, the target resource given in the URL is overwritten even if it is a different type than the resource descriptor in the content. The default is false.

Options

Content-Location: {resourceSourceUri} - Specifies the resource to be copied.

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

404 Not Found – When the {resourceSourceUri} is not valid.

Moving a Resource

Moving a resource uses the PUT method, whereas copying it uses the POST method.

Method

URL

PUT

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

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.

overwrite

true|false

When true, the target resource given in the URL is overwritten even if it is a different type than the resource descriptor in the content. The default is false.

Options

Content-Location: {resourceSourceUri} - Specifies the resource to be moved.

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

404 Not Found – When the {resourceSourceUri} is not valid.

Deleting Resources

The DELETE method has two forms, one for single resources and one for multiple resources.

Method

URL

DELETE

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

Return Value on Success

Typical Return Values on Failure

204 No Content – The request was successful and there is no descriptor to return.

404 Not Found – When the resource path or ID is not valid.

To delete multiple resources at once, specify multiple URIs with the resourceUri parameter.

Method

URL

DELETE

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources?resourceUri={uri}&...

Argument

Type/Value

Description

resourceUri

string

Specifies a resource to delete. You may need to encode the / characters in the URI with %2F. Repeat this parameter to delete multiple resources.

Return Value on Success

Typical Return Values on Failure

204 No Content – The request was successful and there is no descriptor to return.

404 Not Found – When the resourceUri is not valid.

Version: 
Feedback
randomness