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 | 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 | 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 | 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 | 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" }, ...][/code] | /sample/resource/uri Sample Label Sample Description folder 0 2013-07-04T12:18:47 2013-07-04T12:18:47 0 ...[/code] |
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 | 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 | 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 | 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 | 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 | 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 | 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. application/repository. | 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 | ||
| Argument | Type/Value | Description | |
| create | 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. application/repository. | 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:
| ||||||||||||||||||||||||||||||||||||||
| 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. PUT 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 | ||
| 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. application/repository. | 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 | ||
| Argument | Type/Value | Description | |
| create | 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 | ||
| Argument | Type/Value | Description | |
| create | 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. | ||
Recommended Comments
There are no comments to display.