Jump to content
JasperReports Library 7.0 is now available ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    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?<parameters>

    Parameter

    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"    },    ...][/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.

    note-icon-ns_28x28.png.608c9e9539ccaa95e635d466aa06d348.png

    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.

    Parameters of resources for Default Pagination

    Parameter

    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:

    Parameters of resources for Full Page Pagination

    Parameter

    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:

    Parameters of resources for No Pagination

    Parameter

    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

    Parameter

    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

    Parameter

    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
    ?<parameters>

    Parameters

    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 above to overwrite an entire resource. Specify the path of the target resource in the URL and specify resource of the same type. Use overwrite=true to replace a resource of a different type.

    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. You can update the local resources using the hidden folder _file. For more information, see Local Resources.

    As of JasperReports Server 5.5, the PATCH method updates individual descriptor fields on the target resource. It also accepts expressions that modify the descriptor in the Spring Expression Language. This expression language lets you easily modify the structure and values of descriptors.

    Method

    URL

    PATCH

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

    Content-Type

    Content

    application/json

    {    "version" : 0,    "patch":[        {            "field":"label",            "value":"New Label"        },        {            "field":"query",            "value":"/path/to/query/resource"        },        {            "expression":"inputControls.add(new com.jaspersoft.                jasperserver.dto.resources.ClientReference().                setUri('/datatypes/decorate'))"        }    ]}[/code]                    

    application/xml

      0            label        New Label                query        /path/to/query/resource                inputControls.add(new com.jaspersoft.            jasperserver.dto.resources.ClientReference().            setUri('/datatypes/decorate'))            [/code]                    

    Return Value on Success

    Typical Return Values on Failure

    For confirmation, the response contains the full descriptor of the resource that was just modified.

    400 Bad Request – Mismatch between the patch fields and the fields or syntax of the actual descriptor.

    409 Conflict – Old version number; the resource was updated more recently than the last version number received.

    The patch descriptor contains attributes of the target resource. It can't be used to specify the attributes of nested resources. However, you can apply the patch operation directly to the local resource in the hidden _files folder.

    If your client does not support the PATCH method, use the POST method and specify the following HTTP header:

    X-HTTP-Method-Override: PATCH

    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
    ?<parameters>

    Parameters

    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
    ?<parameters>

    Parameters

    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}&...

    Parameter

    Type/Value

    Description

    resourceUri

    string

    Specifies a resource to delete. 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.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...